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Guava 工 程 包含 了 若干 被 Google 的 Java 项 目 广 泛 依赖 的 核心 库 ， 例 如 : 集合 
[collections], #44 [caching] 、 原 生 类 型 支持 [primitives support] 、 并 发 库 
[concurrency libraries] 、 通 用 注解 [common annotations], FEA% H [string 
processing], /O 等 等 。 所 有 这 些 工具 每 天 都 在 被 Google 的 工程 病 应 用 在 产品 服 
务 中 。 


查阅 Javadoc 并 不 一 定 是 学 习 这 些 库 最 有 效 的 方式 。 在 此 ， 我 们 希望 通过 此 文档 为 
Guava 中 最 流行 和 最 强大 的 功能 ， 提 供 更 具 可 读 性 和 解释 性 的 说 明 。 


译文 格式 说 明 


e Guava 中 的 类 被 首次 引用 时 ， 都 会 链接 到 Guava 的 API 文 档 。 
如 : Optional<T>。 

e Guava 和 JDK 中 的 方法 被 引用 时 ， 一 般 都 会 链接 到 Guava 或 JDK 的 API 文 档 ， 一 
些 人 所 共 知 的 JDK 方 法 除外 。 
如 : [Optional.of(T)](http://docs.guava-libraries.googlecode.com/ 
, Map.get(key)。 

。 译 者 对 文档 的 额外 说 明 以 斜体 显示 ， 并 且 以 “ 译 者 注 _ : "开始 。 
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1. 基本 工具 [Basic utilities] 


让 使 用 Java 语 言 变 得 更 舒适 


1.1 使 用 和 避免 null : null 是 模棱两可 的 ， 会 引起 令 人 困惑 的 错误 ， 有 些 时 候 它 让 人 
很 不 舒服 。 很 多 Guava 工 具 类 用 快速 失败 拒绝 null 值 ， 而 不 是 盲目 地 接受 


1.2 MER: 让 方法 中 的 条 件 检查 更 简单 

1.3 常见 Object 方法 : 简化 Object 方 法 实现 ， 如 hashCode() 和 toString() 
1.4 排序 : Guava 强 大 的 "流畅 风格 比较 器 * 

1.5 Throwables : 简化 了 异常 和 错误 的 传播 与 检查 


2. 集合 [Collections] 


Guava 对 JDK 集 合 的 扩展 ， 这 是 Guava 最 成 熟 和 为 人 所 知 的 部 分 
2.1 FARA: 用 不 变 的 集合 进行 防御 性 编程 和 性 能 提升 。 


2.2 新 集合 类 型 : multisets, multimaps, tables, bidirectional maps 等 
2.3 强大 的 集合 工具 类 : 提供 java.util.Collections 中 没有 的 集合 工具 


2.4 扩展 工具 类 : 让 实现 和 扩展 集合 类 变 得 更 容易 ， 比 如 创建 collection 的 装饰 
器 ， 或 实现 迭代 器 


3. 绥 存 [Caches] 

Guava Cache : 本 地 缓存 实现 ， 支 持 多 种 缓存 过 期 策略 
4. KHA [Functional idioms] 
Guava 的 函数 式 支 持 可 以 显著 简化 代码 ， 但 请 着 慎 使 用 它 


5. 并 发 [Concurrency] 


强大 而 简单 的 抽象 ， 让 编写 正确 的 并 发 代码 更 简单 
5.1 ListenableFuture : 完成 后 触发 回调 的 Future 
5.2 Service 框 架 : 抽象 可 开启 和 关闭 的 服务 ， 帮 助 你 维护 服务 的 状态 逮 辑 


6. FFE x 32[Strings] 

非常 有 用 的 字符 串 工具 ， 包 括 分 割 、 连 接 、 填 充 等 操作 

7. 原生 类 型 [Primitives] 

扩展 JDK 未 提供 的 原生 类 型 (如 int、char) 操作 ， 包括 某 些 类 型 的 无 符号 形式 
8. X ja] [Ranges] 

可 比较 类 型 的 区 间 API， 包 括 连续 和 离散 类 型 

9.1/0 


简化 MO 尤其 是 MO 流 和 文件 的 操作 ， 针 对 Java5 和 6 版 本 


10. 散 列 [Hash] 


提供 比 Object.hashCode() 更 复杂 的 散 列 实现 ， 并 提供 布 鲁 姆 过 滤器 的 实现 
11. 事件 总 线 [EventBus] 

发 布 -订阅 模式 的 组 件 通 信 ， 但 组 件 不 需要 显 式 地 注册 到 其 他 组 件 中 

12. 效 学 运算 [Math] 

优化 的 、 充 分 测试 的 数学 工具 类 


13. 反射 [Reflection] 


Guava 的 Java 反射 机 制 工具 类 


1- 基 本 工具 


1.1- 使 用 和 避免 hull 


原文 链接 译文 链接 译 者 : 沈 义 扬 
Doug Lea 说 ，“Null 真 糟糕 。” 
当 Sir C. A. R. Hoare 使 用 了 nul/ 引 用 后 说 ，” 盖 用 它 导致 了 十 亿美 金 的 错误 。” 


轻率 地 使 用 null 可 能 会 导致 很 多 合 人 惊 惯 的 问题 。 通 过 学 习 Google 诡 层 代 码 库 ， 我 
们 发 现 95% 的 集合 类 不 接受 null 值 作为 元 素 。 我 们 认为 ， 相 比 默默 地 接受 null， 使 用 
快速 失败 操作 拒绝 null 值 对 开发 者 更 有 帮助 。 


此 外 ，Null 的 含糊 语义 让 人 很 不 舒服 。Null 很 少 可 以 明确 地 表示 某 种 语义 ， 例 如 ， 
Map.get(key) 返 回 Null 时 ， 可 能 表示 map 中 的 值 是 null， 亦 或 map 中 没有 key 对 应 的 
值 。Null 可 以 表示 失败 、 成 功 或 几乎 任何 情况 。 使 用 Null 以 外 的 特定 值 ， 会 让 你 的 
逻辑 描述 变 得 更 清晰 。 


Null 确 实 也 有 合适 和 正确 的 使 用 场景 ， 如 在 性 能 和 速度 方面 Null 是 廉价 的 ， 而 且 在 
对 象 数组 中 ， 出 现 Null 也 是 无 法 避免 的 。 但 相对 于 底层 库 来 说 ， 在 应 用 级 别 的 代码 
中 ，Null 往 往 是 导致 混乱 ， 疑 难 问 题 和 模糊 语义 的 元 凶 ， 就 如 同 我 们 举 过 的 
Map.get(key) 的 例子 。 最 关键 的 是 ，Null 本 身 没 有 定义 它 表 达 的 意思 。 


鉴于 这 些 原因 ， 很 多 Guava 工 具 类 对 Null 值 都 采用 快速 失败 操作 ， 除 非 工 具 类 本 身 
提供 了 针对 Null 值 的 因 变 措施 。 此 外 ，Guava 还 提供 了 很 多 工具 类 ， 让 你 更 方便 地 
用 特定 值 蔡 换 Null 值 。 


具体 案例 


不 要 在 Set 中 使 用 null， 或 者 把 null 作 为 map 的 键 值 。 使 用 特殊 值 代表 null 会 让 查找 操 
作 的 语义 更 清晰 。 


如 果 你 想 把 null 作 为 map 中 某 条 目的 值 ， 更 好 的 办 法 是 不 把 这 一 条 目 放 到 map 中 ， 
而 是 单独 维护 一 个 " 值 为 null 的 键 集合 " (null keys), Map 中 对 应 某 个 键 的 值 是 null， 
和 map 中 没有 对 应 某 个 键 的 值 ， 是 非常 容易 混淆 的 两 种 情况 。 因 此 ， 最 好 把 值 为 
null 的 键 分 离开 ， 并 且 仔 细 想 想 ，null 值 的 键 在 你 的 项 目 中 到 诡 表 达 了 什么 语义 。 


如 果 你 需要 在 列表 中 使 用 null 一 一 并 且 这 个 列表 的 数据 是 稀 足 的 ， 使 用 
Map<lnteger E> 可 能 会 更 高 效 ， 并 且 更 准确 地 符合 你 的 潜在 需求 。 


此 外 ， 考 虑 一 下 使 用 自然 的 null 对 象 一 一 特殊 值 。 举 例 来 说 ， 为 某 个 enum 类 型 增加 
特殊 的 枚 举 值 表示 null， 比 如 java.math.RoundingMode 就 定义 了 一 个 枚 举 值 
UNNECESSARY， 它 表示 一 种 不 做 任何 舍 人 操作 的 模式 ， 用 这 种 模式 做 伟人 操作 
会 直接 抛 出 异常 。 


如 果 你 真 的 需要 使 用 null 值 ， 但 是 null 值 不 能 和 Guava 中 的 集合 实现 一 起 工作 ， 你 只 
能 选择 其 他 实现 。 比 如 ， 用 JDK 中 的 Collections.unmodifiableList 替 代 Guava 的 
ImmutableList 





Optional 


大 多 数 情况 下 ， 开 发 人 员 使 用 null 表 明 的 是 某 种 缺失 情形 : 可 能 是 已 经 有 一 个 默认 
值 ， 或 没有 值 ， 或 找 不 到 值 。 例 如 ，Map.get 返 回 null 就 表示 找 不 到 给 定 键 对 应 的 
值 。 


Guava 用 Optional<T> 表 示 可 能 为 null 的 T 类 型 引用 。 一 个 Optional 实 例 可 能 包含 非 
null 的 引用 (我 们 称 之 为 引用 存在 ) ， 也 可 能 什么 也 不 包括 〈 称 之 为 引用 缺失 ) 。 
它 从 不 说 包含 的 是 null 值 ， 而 是 用 存在 或 缺失 来 表示 。 但 Optional 从 不 会 包含 null 值 
引用 。 

Optional<Integer> possible = Optional.of(5); 

possible.isPresent(); // returns true 

possible.get(); // returns 5 


Optional 无 意 直接 模拟 其 他 编程 环境 中 的 "可 选 " or 可能" 语义， 但 它们 的 确 有 相似 
之 处 。 


Optional 最 常用 的 一 些 操作 被 罗列 如 下 : 
创建 Optional 实 例 〈 以 下 都 是 静态 方法 ) 


创建 指定 引用 的 Optional 实 例 ， 若 引用 为 
Optional.of(T) null 则 快速 失败 
Optional.absent() 创建 引用 缺失 的 Optional 实 例 

创建 指定 引用 的 Optional 实 例 ， 若 引用 为 null 
Optional.fromNullable(T) 则 表示 缺失 


用 Optional 实 例 查询 引用 〈 以 下 都 是 非 静态 方法 ) 
如 果 Optional 包 含 非 null 的 引用 (引用 存在 ) ， 


boolean isPresent() 


返回 true 
SEO 返回 Optional 所 包含 的 引用 ， 若 引用 缺失 ， 则 抛 
出 java.lang.lllegalStateException 
返回 Optional 所 包含 的 引用 ， 若 引用 缺失 ， 返 回 
sea 指定 的 值 
T ornull() See 若 引 用 缺失 ， 返 回 


返回 Optional 所 包含 引用 的 单 例 不 可 变 集 ， 如 果 
SEEL Te sasses 人 二 引用 存在 ， 返 回 一 个 只 有 单一 元 素 的 集合 ， 如 果 
引用 缺失 ， 返 回 一 个 空 集 合 。 


使 用 *Optional* 的 意义 在 哪儿 ? 


使 用 Optional 除 了 赋予 null 语 义 ， 增 加 了 可 读 性 ， 最 大 的 优点 在 于 它 是 一 种 傻瓜 式 的 
防护 。Optional 人 迫使 你 积极 思考 引用 缺失 的 情况 ， 因 为 你 必须 显 式 地 从 Optional 获 
取 引 用 。 直 接 使 用 null 很 容易 让 人 忘掉 某 些 情形 ， 尽 管 FindBugs 可 以 帮助 查找 null 相 
关 的 问题 ， 但 是 我 们 还 是 认为 它 并 不 能 准确 地 定位 问题 根源 。 


如 同 输入 参数 ， 方 法 的 返回 值 也 可 能 是 null。 和 其 他 人 一 样 ， 你 绝对 很 可 能 会 忘记 
别人 写 的 方法 method(a,b) 会 返回 一 个 null， 就 好 像 当 你 实现 method(a,b) 时 ， 也 很 可 
能 忘记 输入 参数 a 可 以 为 null。 将 方法 的 返回 类 型 指定 为 Optional， 也 可 以 迫使 调用 
者 思考 返回 的 引用 缺失 的 情形 。 


其 他 人 处理 null 的 便利 方法 


当 你 需要 用 一 个 默认 值 来 替换 可 能 的 null， 请 使 

用 Objects.firstNonNull(T, T) 方法 。 如 果 两 个 值 都 是 null， 该 方法 会 抛 出 
NullPointerException。 Optional 也 是 一 个 比较 好 的 替代 方案 ， 例 如 : 
Optional.of(first).or(second). 


还 有 其 它 一 些 方 法 专门 处 理 null 或 空 字符 

FB: emptyToNull(String), nullToEmpty(String) , isNullorEmpty(String) 
。 我 们 想 要 强调 的 是 ， 这 些 方 法 主要 用 来 与 混淆 null 空 的 API 进 行 交 互 。 当 每 次 你 写 
下 混淆 nully 空 的 代码 时 ，Guava 团 队 都 泪 流 满面 。 (好 的 做 法 是 积极 地 把 nyull 和 空 区 
分 开 ， 以 表示 不 同 的 含义 ， 在 代码 中 把 null 和 空 同等 对 待 是 一 种 令 人 不 安 的 坏 味 


道 。 


1.2-5) E RIF 


原文 链接 译文 链接 译 者 : 沈 义 扬 
前 置 条 件 : 让 方法 调用 的 前 置 条 件 判 断 更 简单 。 


Guava 在 Preconditions 类 中 提供 了 若干 前 置 条 件 判 断 的 实用 方法 ， 我 们 强烈 建议 在 
Eclipse 中 静态 导入 这 些 方法 。 每 个 方法 都 有 三 个 变种 : 


。 没有 额外 参数 : 抛 出 的 异常 中 没有 错误 消息 ; 

° E 额外 参数 : 抛 出 的 录 常 使 用 Object.toString() 作为 错误 

pee ASiga EA SNS, REES MRO : 这 
个 变种 义理 异常 消息 的 方式 有 点 类 似 printf， 但 考虑 GWT 的 兼容 性 和 效率 ， 只 
支持 %s 指 示 符 。 例 如 : 


checkArgument(i >= 0, "Argument was %s but expected nonnegative", 
checkArgument(i < j, "Expected i < j, but %s > %s", i, j); 





方法 声明 (不 包括 额外 参数 ) 


checkArgument (boolean) 


checkNotNull(T) 


checkState(boolean) 


checkElementIndex(int index, int size) 


checkPositionIndex(int index, int size) 


checkPositioniIndexes(int start, 


译 者 注 : 


int end, 


描述 


检查 boolean 是 
Atrue, FAK 
传递 给 合 方 法 的 3 


o 


检查 value 是 否 
null， 该 方法 直 
返回 value， 
BY LAA Bre (8 FB 
checkNotNull 


FURS BH xt RE 
某 些 状态 。 


检查 index 作 为 
引 值 对 某 个 列 
R SPB 
组 是 否 有 效 。 
index>=0 && 
index<size * 


检查 index 作 为 
置 值 对 某 个 列 
R, SRB RF 
组 是 否 有 效 。 
index>=0 && 
index<=size * 


检查 [start, end 
示 的 位 置 范围 x 
某 个 列表 、 字 和 
串 或 数组 是 否 
效 * 


* 床 引 值 常用 来 查找 列表 、 字 符 串 或 数组 中 的 元 素 ， 如 List.get(int), String.charAt(int) 


* 位 置 值 和 位 置 范围 常用 来 截取 列表 、 字 符 串 或 数组 ， 如 List.subList(int，int), 
String.substring(int) 


相 比 Apache Commons 提 供 的 类 似 方法 ， 我 们 把 Guava 中 的 Preconditions 作 为 首 


选 。 Piotr Jagielski 在 他 的 博客 中 简要 地 列举 了 一 些 理由 : 
° 在 静态 导入 后 百 ，Guava 方 法 非常 清楚 明晰 。checkNotNull; 


么 ， 会 抛 出 什么 异常 ; 
e checkNotNull 直 接 返 回 检 查 的 参数 ， 让 你 可 以 在 构造 画 数 中 保持 字段 的 单行 赋 


值 风格 : 
。 简单 的 、 


this.field = checkNotNull(field) 


地 描述 做 了 什 


参数 可 变 的 printf 风 格 异 常 信 息 。 鉴 于 这 个 优点 ， 在 JDK7 已 经 引 


入 Objects.requireNonNull 的 情况 下 ， 我 们 仍然 建议 你 使 用 checkNotNull。 


在 编码 时 ， 如 果 某 个 值 有 多 重 的 前 置 条 件 ， 我 们 建议 你 把 它们 放 到 不 同 的 行 ， 这 样 
有 助 于 在 调试 时 定位 。 此 外 ， 把 每 个 前 置 条 件 放 到 不 同 的 行 ， 也 可 以 帮助 你 编写 清 
晰 和 有 用 的 错 误 消 息 。 


1.3- 常 见 Object 方 法 


原文 链接 译 者 : 沈 义 扬 
equals 
当 一 个 对 象 中 的 字段 可 以 为 null 时 ， 实 现 Object.equals 方 法 会 很 痛苦 ， 因 为 不 得 不 


分 别 对 它们 进行 hull 检 查 。 使 用 Objects.equal 帮助 你 执行 null 敏 感 的 equals 判 
断 ， 从 而 避免 抛 出 NullPointerException。 例 如 : 


Objects.equal("a", "a"); // returns true 

Objects.equal(null, "a"); // returns false 
Objects.equal("a", null); // returns false 
Objects.equal(null, null); // returns true 


注意 : JDK7 引 入 的 Objects 类 提供 了 一 样 的 方法 _Objects.equals_ o 
hashCode 

用 对 象 的 所 有 字段 作 散 列 [hash] 运 算 应 当 更 简单 。Guava 

的 Objects.hashCode(Object...) 会 对 传 入 的 字段 序列 计算 出 合理 的 、 顺 序 敏 


感 的 散 列 值 。 你 可 以 使 用 Objects.hashCode(field1, field2, ..., fieldn) 来 代替 手动 计 
算 散 列 值 。 


注意 : JDK7 引 入 的 Objects 类 提供 了 一 样 的 方法 _Objects.hash(Object...)_ 
toString 


好 的 toString 方 法 在 调试 时 是 无 价 之 宝 ， 但 是 编写 toString 方 法 有 时 候 却 很 痛苦 。 使 
用 Objects.toStringHelper 可 以 轻松 编写 有 用 的 toString 方 法 。 例 如 : 


// Returns "ClassName{x=1}" 
Objects.toStringHelper(this).add("x", 1).toString(); 

// Returns "MyObject{x=1}" 
Objects.toStringHelper("MyObject").add("x", 1).toString(); 


compare/compareTo 


实现 一 个 比较 器 [Comparatorl]， 或 者 直接 实现 Comparable 接 口 有 时 也 伤 不 起 。 考 虑 
一 下 这 种 情况 : 


class Person implements Comparable<Person> { 
private String lastName; 
private String firstName; 
private int zipCode; 


public int compareTo(Person other) { 
int cmp = lastName.compareTo(other.lastName); 
if (cmp != 0) { 
return cmp; 
} 
cmp = firstName.compareTo(other.firstName) ; 
if (cmp != 0) { 
return cmp; 


return Integer.compare(zipCode, other.zipCode); 


这 部 分 代码 太 琐碎 了 ， 因 此 很 容易 摘 乱 ， 也 很 难 调试 。 我 们 应 该 能 把 这 种 代码 变 得 
更 优雅 ， 为 此 ，Guava 提 供 了 ComparisonChain o 


ComparisonChain 执 行 一 种 懒 比 较 : 它 执行 比较 操作 直至 发 现 非 需 的 结果 ， 在 那 之 
后 的 比较 输入 将 被 忽略 。 


public int compareTo(Foo that) { 
return ComparisonChain.start() 
.compare(this.aString, that.aString) 
.compare(this.anInt, that.anInt) 
.compare(this.anEnum, that.anEnum, Ordering.natural().1 
.result(); 





这 种 Fluent 接 口 风格 的 可 读 性 更 高 ， 发 生 错误 编码 的 几率 更 小 ， 并 且 能 避免 做 不 必 
要 的 工作 。 更 多 Guava 排 序 器 工具 可 以 在 下 一 节 里 找到 。 


1.4- 排 序 : Guava 强 大 的 ”流畅 风格 比较 器 ” 


原文 链接 译 者 : 沈 义 扬 


排序 器 [Ordering] 是 Guava 流 畅 风 格 比 较 器 [Comparator] 的 实现 ， 它 可 以 用 来 为 构建 
复杂 的 比较 器 ， 以 完成 集合 排序 的 功能 。 


从 实现 上 说 ，Ordering 实 例 就 是 一 个 特殊 的 Comparator 实 例 。Ordering 把 很 多 基于 
Comparator 的 静态 方法 (如 Collections.max) 包装 为 自己 的 实例 方法 ( 非 静 态 方 
法 ) ， 并 且 提 供 了 链 式 调用 方法 ， 来 定制 和 增强 现 有 的 比较 器 。 


创建 排序 器 : 常见 的 排序 器 可 以 由 下 面 的 静态 方法 创建 


方法 描述 

对 可 排序 类 型 做 自然 排序 ， 如 数字 按 大 小 ， 日 期 按 先 
natural() 后 排序 

按 对 象 的 字符 串 形 式 做 字典 排序 [lexicographical 


usingToStrin 
` I0) ordering] 


from(Comparator) 把 给 定 的 Comparator 转 化 为 排序 器 


实现 自 定义 的 排序 器 时 ， 除 了 用 上 面 的 from 方 法 ， 也 可 以 跳 过 实现 Comparator， 而 
直接 继承 Ordering : 


Ordering<String> byLengthordering = new Ordering<String>() { 
public int compare(String left, String right) { 
return Ints.compare(left.length(), right.length()); 


je 


链 式 调用 方法 : 通过 链 式 调用 ， 可 以 由 给 定 的 排序 器 衍生 出 其 它 排序 器 


方法 描述 


reverse() 获取 语义 相反 的 排序 器 

nullsFirst() 使 用 当前 排序 器 ， 但 额外 把 null 值 排 到 最 前 面 。 

nullsLast() 使 用 当前 排序 器 ， 但 额外 把 null 值 排 到 最 后 面 。 

compound(Comparator) a 以 义理 当前 排序 器 中 的 相等 
月 人 Lo 


基于 义理 类 型 T 的 排序 器 ， 返 回 该 类 型 的 可 迭代 
对 象 lterable<T> 的 排序 器 。 


对 集合 中 元 素 调 用 Function， 再 按 返 回 值 用 当前 
排序 器 排序 。 


例如 ， 你 需要 下 面 这 个 类 的 排序 器 。 


lexicographical() 


onResultOf (Function) 


class Foo { 
@Nullable String sortedBy; 
int notSortedBy; 


考虑 到 排序 器 应 该 能 处 理 sortedBy 为 null 的 情况 ， 我 们 可 以 使 用 下 面 的 链 式 调用 来 
合成 排序 器 : 


Ordering<Foo> ordering = Ordering.natural().nullsFirst().onResulto1 
public String apply(Foo foo) { 
return foo.sortedBy; 


} 
}); 


当 阅 读 链 式 调用 产生 的 排序 器 时 ， 应 该 从 后 往 前 读 。 上 面 的 例子 中 ， 排 序 器 首先 调 
用 apply 方 法 获取 sortedBy 值 ， 并 把 sortedBy 为 null 的 元 素 都 放 到 最 前 面 ， 然 后 把 剩 
下 的 元 素 按 sortedBy 进 行 自然 排序 。 之 所 以 要 从 后 往 前 读 ， 是 因为 每 次 链 式 调用 都 
是 用 后 面 的 方法 包装 了 前 面 的 排序 器 。 


注 : 用 compound 方 法 包装 排序 器 时 ， 就 不 应 遵循 从 后 往 前 读 的 原则 。 为 了 避免 理 
解 上 的 混乱 ， 请 不 要 把 compound 写 在 一 长 串 链 式 调用 的 中 间 ， 你 可 以 另 起 一 行 ， 
在 链 中 最 先 或 最 后 调用 compound。 


超过 一 定 长 度 的 链 式 调 用 ， 也 可 能 会 带 来 阅读 和 理解 上 的 难度 。 我 们 建议 按 下 面 的 
代码 这 样 ， 在 一 个 链 中 最 多 使 用 三 个 方法 。 此 外 ， 你 也 可 以 把 Function 分 离 成 中 间 
对 象 ， 让 链 式 调用 更 简洁 紧凑 。 





Ordering<Foo> ordering = Ordering.natural().nullsFirst().onResulto1 
Ms= = = 一 一 
运用 排序 器 : Guava 的 排序 器 实现 有 若干 操纵 集合 或 元 素 值 的 方法 





方法 描述 
greatestOf(Iterable iterable, int k) Se eee 

判断 可 和 迭代 对 象 是 否 已 按 排 
isOrdered(Iterable) 序 器 排序 : 允许 有 排序 值 相 

等 的 元 素 。 

判断 可 迁 代 对 象 是 否 已 严格 
sortedCopy(Iterable) 按 排序 器 排序 : 不 允许 排序 

值 相等 的 元 素 。 

返回 两 个 参数 中 最 小 的 那 
min(E, E) 个 。 如 果 相 等 ， 则 返回 第 一 

个 参数 。 

ra ae a LM 

: 个 。 如 果 有 超过 一 个 参数 都 

和 最 小 ， 则 返回 第 一 个 最 小 的 

参数 。 


返回 迭代 器 中 最 小 的 元 素 。 
如 果 可 和 迭代 对 象 中 没有 元 
素 ， 则 抛 出 


NoSuchElementException。 


min(Iterable) 


1.5-Throwables : 简化 异常 和 错误 的 传播 与 检查 


原文 链接 译 者 : 沈 义 扬 


寞 前 传播 


有 时 候 ， 你 会 想 把 捕获 到 的 异常 再 次 抛 出 。 这 种 情况 通常 发 生 在 Error 或 
RuntimeException 被 捕获 的 时 候 ， 你 没 想 捕 获 它 们 ， 但 是 声明 捕获 Throwable 和 
Exception 的 时 候 ， 也 包括 了 了 Error 或 RuntimeException。Guava 提 供 了 若干 方 
法 ， 来 判断 异常 类 型 并 且 重 新 传播 异常 。 例 如 : 


try { 
someMethodThatCouldThrowAnything(); 

} catch (IKnowwhatToDoWithThisException e) { 
handle(e); 

} catch (Throwable t) { 
Throwables.propagateIfiInstanceOf(t, IOException.class); 
Throwables.propagateIfiInstanceOf(t, SQLException.class); 
throw Throwables.propagate(t); 


所 有 这 些 方 法 都 会 自己 决定 是 否 要 抛 出 异常 ， 但 也 能 直接 抛 出 方法 返回 的 结果 一 一 
例如 ，throw Throwables.propagate(t);—— 这 样 可 以 向 编译 器 声明 这 里 一 定 会 抛 出 


ny 
Ba 


Guava 中 的 异常 传播 方法 简要 列举 如 下 : 


如 果 Throwable 是 Error 或 RuntimeException， 直 
接 抛 出 ; 否则 把 Throwable 包 装 成 
RuntimeException RuntimeException 抛 出 。 返 回 类 型 是 
propagate(Throwable) RuntimeException， 所 以 你 可 以 像 上 面 说 的 那样 罕 
成 throw Throwables.propagate(t) ，Java 编 译 
中 会 意识 到 这 行 代 码 保证 抛 出 异常 。 


void 

propagatelflnstanceOf( 

Throwable, Class<X Throwable 类 型 为 X 才 抛 出 
extends Exception>) 

throws X 


void 
propagatelfPossible( Throwable # 2! % Errors&RuntimeException> #04 
Throwable) 


void 
propagatelfPossible( se FE 、 = , , 
Throwable, Class<X i Error 或 RuntimeException 才 抛 


extends Throwable>) 
throws X 


Throwables.propagate 的 用 法 


模仿 Java7 的 多 重 异 常 捕获 和 再 抛 出 


通常 来 说 ， 如 果 调 用 者 想 让 异常 传播 到 栈 项 ， 他 不 需要 写 任 何 catch 代 码 块 。 因 为 他 
不 打算 从 异常 中 恢复 ， 他 可 能 就 不 应 该 记录 异常 ， 或 者 有 其 他 的 动作 。 他 可 能 是 想 
做 一 些 清理 工作 ， 但 通常 来 说 ， 无 论 操 作 是 否 成 功 ， 清 理工 作 都 要 进行 ， 所 以 清理 
工作 可 能 会 放 在 finallly 代 码 块 中 。 但 有 时 候 ， 捕 获 异 常 然后 再 抛 出 也 是 有 用 的 : 也 
许 调 用 者 想 要 在 异常 传播 之 前 统计 失败 的 次 数 ， 或 者 有 条 件 地 传播 异常 。 


当 只 对 一 种 异常 进行 捕获 和 再 抛 出 时 ， 代 码 可 能 还 是 简单 明了 的 。 但 当 多 种 异常 需 
要 久 理 时 ， 却 可 能 变 得 一 团 粳 : 


@Override public void run() { 

try { 
delegate.run(); 

} catch (RuntimeException e) { 
failures.increment(); 
throw e; 

catch (Error e) { 
failures.increment(); 
throw e; 


Java7 用 多 重 捕获 解决 了 这 个 问题 : 


} catch (RuntimeException | Error e) { 
failures.increment(); 
throw e; 


非 Java7 用 户 却 受 困 于 这 个 问题 。 他 们 想 要 写 如 下 代码 来 统计 所 有 异常 ， 但 是 编译 
器 不 允许 他 们 抛 出 Throwable ( 译 者 注 : 这 种 写法 把 原本 是 Errol 或 
es 类 型 的 异常 修改 成 了 Throwable， 因 此 调用 者 不 得 不 修改 方法 签 
名 ) 


} catch (Throwable t) { 
failures.increment(); 
throw t; 


解决 办 法 是 用 throw Throwables.propagate(t)# throw t。 在 限定 情况 下 (捕获 
Error 和 RuntimeException) ，Throwables.propagate 和 原始 代码 有 相同 行为 。 然 
而 ， 用 Throwables.propagate 也 很 容易 写 出 有 其 他 隐藏 行 为 的 代码 。 尤 其 要 注意 的 
T, 这 个 方案 只 适用 于 处理 RuntimeException Error, WRcatchi tA T ZRF 
常 ， 你 需要 调用 propagatelflnstanceOf 来 保留 原始 代码 的 行为 ， 因 为 
Throwables.propagate 不 能 直接 传播 受 检 腊 常 。 


总 之 ，Throwables.propagate 的 这 种 用 法 也 就 马马虎虎 ， 在 Java7 中 就 没 必 要 这 样 
做 了 。 在 其 他 Java 版 本 中 ， 它 可 以 减少 少量 的 代码 重复 ， 但 简单 地 提取 方法 进行 重 
构 也 能 做 到 这 一 点 。 此 外 ， 使 用 propagate 会 意外 地 包装 受 检 腊 常 。 


非 必 要 用 法 : 把 抛 出 的 Throwable 转 为 Exception 


有 少数 API， 尤 其 是 Java 反 射 APl 和 (以 此 为 基础 的 ) Junit， 把 方法 声明 成 抛 出 
Throwable。 和 这 样 的 API 交 互 太 痛苦 了 ， 因 为 即使 是 最 通用 的 API 通 常 也 只 是 声明 
抛 出 Exception。 当 确定 代码 会 抛 出 Throwable， 而 不 是 Exception 或 Error 时 ， 调 用 
者 可 能 会 用 Throwables.propagate 转 化 Throwable。 这 里 有 个 用 Callable 执 行 Junit 测 
试 的 范例 : 


public Void call() throws Exception { 
try { 
FooTest.super.runTest(); 

} catch (Throwable t) { 
Throwables.propagateIfPossible(t, Exception.class); 
Throwables.propagate(t); 

} 


return null; 


在 这 儿 没 必要 调用 propagate() 方 法 ， 因 为 propagatelfPossible 传 播 了 Throwable 之 
外 的 所 有 异常 类 型 ， 第 二 行 的 propagate 就 变 得 完全 等 价 于 throw new 
RuntimeException(t)。 ( 题 外 话 : 这 个 例子 也 提醒 我 们 ，propagatelfPossible 可 能 
也 会 引起 混乱 ， 因 为 它 不 但 会 传播 参数 中 给 定 的 异常 类 型 ， 还 抛 出 Error 和 
RuntimeException) 


这 种 模式 (或 类 似 于 throw new RuntimeException(t) 的 模式 ) 在 Google 代 码 库 中 出 


现 了 超过 30 次 。 (搜索 'propagatelfPossible'* Exception.class[)];) 绝 大 多 数 情况 
下 都 明确 用 了 ”throw new RuntimeException(t)”。 我 们 也 合 想 过 有 

个 ”throwWrappingWeirdThrowable” 方 法 处 理 Throwable 到 Exception 的 转化 。 但 考 
虑 到 我 们 用 两 行 代 码 实现 了 这 个 模式 ， 除 非 我 们 也 丢弃 propagatelfPossible 方 法 ， 
不 然 定 义 这 个 throwWrappingWeirdThrowable 方 法 也 并 没有 太 大 必要 。 


Throwables.propagate 的 有 和 争议 用 法 


争议 一 : 把 受 检 异常 转化 为 非 受 检 异 常 


原则 上 ， 非 受 检 异 常 代表 bug， 而 受 检 异常 表示 不 可 控 的 问题 。 但 在 实际 运用 中 ， 
即使 JDK 也 有 所 误 用 一 一 如 Object.clone()、Integer. parselnt(String)、URI(String) 
或 者 至 少 对 某 些 方法 来 说 ， 没 有 让 每 个 人 都 信服 的 答案 ， 如 URl.create(String) 
的 异常 声明 。 


因此 ， 调 用 者 有 时 不 得 不 把 受 检 异 常 和 非 受 检 异 常 做 相互 转化 : 





try { 
return Integer.parseInt(userInput) ; 


} catch (NumberFormatException e) { 
throw new InvalidInputException(e); 
} 


try { 
return publicInterfaceMethod.invoke(); 


} catch (IllegalAccessException e) { 
throw new AssertionError(e); 
} 


有 时 候 ， 调 用 者 会 使 用 Throwables.propagate 转 化 异常 。 这 样 做 有 没有 什么 缺点 ? 
最 主要 的 恐怕 是 代码 的 含义 不 太 明 显 。throw Throwables.propagate(ioException) 
做 了 什么 ?throw new RuntimeException(ioException) 做 了 什么 ?这 两 者 做 了 同样 
的 事情 ， 但 后 者 的 意思 更 简单 直接 。 前 者 却 引 起 了 疑问 : " 它 做 了 什么 ? 它 并 不 只 是 
把 异常 包装 进 RuntimeException 吧 ? 如 果 它 真 的 只 做 了 包装 ， 为 什么 还 非得 要 写 个 
方法 ?”。 应 该 承认 ， 这 些 问题 部 分 是 因为 "propagate" 的 语义 太 模糊 了 〈 用 来 抛 出 
ARAM Sy?) 。 也 许 ”WraplfChecked” 更 能 清楚 地 表达 含义 。 但 即使 方法 叫 
做 ”wraplfChecked”， 用 它 来 包装 一 个 已 知 类 型 的 受 检 异常 也 没什么 优点 。 其 至 会 


其 他 缺点 : 也 许 比 起 RuntimeException， 还 有 更 合适 的 类 型 一 一 如 
lllegalArgumentException。 我 们 有 时 也 会 看 到 propagate 被 用 于 传播 可 能 为 受 检 的 
异常 ， 结 果 是 代码 相 比 以 前 会 稍微 简短 点 ， 但 也 稍微 有 点 不 清晰 : 


} catch (RuntimeException e) { 
throw e; 
}catch (Exception e) { 
throw new RuntimeException(e); 
} 


} catch (Exception e) { 
throw Throwables.propagate(e); 


} 


然而 ， 我 们 似乎 故意 忽略 了 把 检查 型 异常 转化 为 非 检查 型 异常 的 合理 性 。 在 某 些 场 
景 中 ， 这 无 疑 是 正确 的 做 法 ， 但 更 多 时 候 它 被 用 于 避免 处 理 受 检 腊 常 。 这 让 我 们 的 
话题 变 成 了 争论 受 检 腊 常 是 不 是 坏 主意 了 ， 我 不 想 对 此 多 做 叙述 。 但 可 以 这 样 说 ， 
Throwables.propagate 不 是 为 了 鼓励 开发 者 忽略 IOException 这 样 的 异常 。 


争议 二 : 异常 穿 除 


但 是 ， 如 果 你 要 实现 不 允许 抛 出 异常 的 方法 呢 ?有 时 候 你 需要 把 异常 包装 在 非 受 检 
异常 内 。 这 种 做 法 挺 好 ， 但 我 们 再 次 强调 ， 没 必要 用 propagate 方 法 做 这 种 简单 的 
包装 。 实 际 上 ， 手 动 包装 可 能 更 好 : 如 果 你 手动 包装 了 所 有 异常 (而 不 仅仅 是 受 检 
异常 ) ， 那 你 就 可 以 在 另 一 端 解 包 所 有 异常 ， 并 处理 极 少数 特殊 场景 。 此 外 ， 你 可 
能 还 想 把 异常 包装 成 特定 的 类 型 ， 而 不 是 像 propagate 这 样 统一 包装 成 
RuntimeException. 


争议 三 : 重新 抛 出 其 他 线程 产生 的 异 前 


try { 
return future.get(); 
} catch (ExecutionException e) { 
throw Throwables.propagate(e.getCause()); 


} 


对 这 样 的 代码 要 考虑 很 多 方面 : 


e ExecutionException 的 cause 可 能 是 受 检 有 异常 ， 见 上 文 " 争 议 一 : 把 检查 型 异常 
转化 为 非 检 查 型 异常 "。 但 如 果 我 们 确定 future 对 应 的 任务 不 会 抛 出 受 检 了 异常 
呢 ? (可 能 future 表 示 runnable 任 务 的 结果 一 一 译 者 注 : 如 ExecutorService 
中 的 submit(Runnable task, T result) 方 法 ) 如 上 所 述 ， 你 可 以 捕获 异常 并 抛 出 
AssertionError。 尤 其 对 于 Future， 请 考虑 Futures.gethi& (TODO: 对 
future.get() 抛 出 的 另 一 个 异常 InterruptedException 作 一 些 说 明 ) 





e ExecutionException 的 cause 可 能 直接 是 Throwable 类 型 ， 而 不 是 Exception 或 
Error, 〈 实 际 上 这 不 大 可 能 ， 但 你 想 直接 重新 抛 出 cause 的 话 ， 编 译 器 会 强迫 
你 考虑 这 种 可 能 性 ) 见 上 文 "用 法 二 : 把 抛 出 Throwable 改 为 抛 出 Exception”。 

ExecutionException 的 cause 可 能 是 非 受 检 腊 常 。 如 果 是 这 样 的 话 ，cause 会 直 
接 被 Throwables.propagate 抛 出 。 不 幸 的 是 ，cause 的 堆栈 信息 反映 的 是 异常 
最 初 产生 的 线程 ， 而 不 是 传播 异常 的 线程 。 通 常 来 说 ， 最 好 在 异常 链 中 同时 包 
含 这 两 个 线程 的 堆栈 信息 ， 就 像 ExecutionException 所 做 的 那样 。 (这 个 问题 
并 不 单单 和 propagate 方 法 相关 ; 所 有 在 其 他 线程 中 重新 抛 出 异常 的 代码 都 需 
要 考虑 这 点 ) 


F mals 


Guava 提 供 了 如 下 三 个 有 用 的 方法 ， 让 研究 异常 的 原因 链 变 得 稍微 简便 了 ， 这 三 个 
方法 的 签名 是 不 言 自明 的 : 

Throwable getRootCause(Throwable) 

List<Throwable> getCausalChain(Throwable) 

String getStackTraceAsString(Throwable) 


2- 集 


2.1- RRA 


原文 链接 译 者 : 沈 义 扬 
564] 


public static final ImmutableSet<String> COLOR_NAMES = ImmutableSetl 
" red" ; 
"orange", 
"yellow", 
"green", 
"blue", 
"purple"); 


class Foo { 
Set<Bar> bars; 
Foo(Set<Bar> bars) { 
this.bars = ImmutableSet.copyOf(bars); // defensive copy! 





为 什么 要 使 用 不 可 变 集 合 
不 可 变 对 象 有 很 多 优点 ， 包 括 : 


o 当 对 象 被 不 可 信 的 库 调用 时 ， 不 可 变形 式 是 安全 的 ; 

。 不 可 变 对 象 被 多 个 线程 调用 时 ， 不 存在 竞 态 条 件 问 题 

。 不 可 变 集合 不 需要 考虑 变化 ， 因 此 可 以 节省 时 间 和 空间 。 所 有 不 可 变 的 集合 都 
比 它们 的 可 变形 式 有 更 好 的 内 存 利用 率 (分 析 和 测试 细节 ) ; 

e 不 可 变 对 象 因为 有 固定 不 变 ， 可 以 作为 常量 来 安全 使 用 。 


创建 对 象 的 不 可 变 拷 贝 是 一 项 很 好 的 防御 性 编程 技巧 。Guava 为 所 有 JDK 标 准 集合 
类 型 和 Guava 新 集合 类 型 都 提供 了 简单 易 用 的 不 可 变 版 本 。 JDK 也 提供 了 
Collections.unmodifiableXXX 方 法 把 集合 包装 为 不 可 变形 式 ， 但 我 们 认为 不 够 好 : 


。 KEMARA: 不 能 舒适 地 用 在 所 有 想 做 防御 性 拷贝 的 场景 ; 

e 不 安全 : 要 保证 没 人 通过 原 集 合 的 引用 进行 修改 ， 返 回 的 集合 才 是 事实 上 不 可 
变 的 ; 

e BEA: 包装 过 的 集合 仍然 保有 可 变 集 合 的 开销 ， 比 如 并 发 修改 的 检查 、 散 列表 
的 额外 空间 ， 等 等 。 


如 果 你 没有 修改 某 个 集合 的 需求 ， 或 者 希望 有 录 个 集合 保持 不 变 时 ， 把 它 防御 性 地 捕 
贝 到 不 可 变 集合 是 个 很 好 的 实践 。 


重要 提示 : 所 有 Guava 不 可 变 集合 的 实现 都 不 接受 nul/ 值 。 我 们 对 Google 内 部 的 代 
码 库 做 过 详细 人 研究， 发 现 只 有 5% 的 情况 需要 在 集合 中 人 允许 nul/ 元 素 ， 剩 下 的 95% 场 
景 都 是 遇 到 nul/ 值 就 快速 失败 。 如 果 你 需要 在 不 可 变 集合 中 使 用 nul/， 请 使 用 JDK 中 
的 Collections.unmodifiableXXX 方 法 。 更 多 细节 建议 请 参考 ” 哑 用 和 避免 hul/” 


怎么 使 用 不 可 交集 合 
不 可 变 集合 可 以 用 如 下 多 种 方式 创建 : 
e copyOf 方 法 ， 如 ImmutableSet.copyOf(set); 


e of 方法 ， 如 |ImmutableSet.of(“a”,“b”，, “c”) 或 ImmutableMap.of(‘a”, 1, “b”, 2); 
e Builder 工 具 ， 如 


public static final ImmutableSet<Color> GOOGLE COLORS = 
ImmutableSet .<Color>builder( ) 
.addAl1(WEBSAFE_COLORS) 
.add(new Color(0, 191, 255)) 
.build(); 


此 外 ， 对 有 序 不 可 变 集 合 来 说 ， 排 序 是 在 构造 集合 的 时 候 完成 的 ， 如 : 


ImmutableSortedSet.of("a", "b", "c", "a", "d", "b"); 


会 在 构造 时 就 把 元 素 排序 为 a, b,c, do 


比 想 象 中 更 智能 的 copyOf 


请 注意 ，ImmutableXXX.copyOf 方 法 会 尝试 在 安全 的 时 候 避 免 做 拷贝 一 一 实际 的 实 
现 细节 不 详 ， 但 通常 来 说 是 很 智能 的 ， 上 比如 : 


ImmutableSet<String> foobar = ImmutableSet.of("foo", "bar", "baz"), 
thingamajig( foobar); 


void thingamajig(Collection<String> collection) { 
ImmutableList<String> defensiveCopy = ImmutableList.copyOf(col- 


ss 





在 这 段 代 码 中 ，ImmutableList.copyOf(foobam) 会 智能 地 直接 返回 foobar.asList(), 它 
是 一 个 ImmutableSet 的 常量 时 间 复 条 度 的 List 视 图 。 作为 一 种 探索 ， 
ImmutableXXX.copyOf(ImmutableCollection) 会 试图 对 如 下 情况 避免 线性 时 间 拷 
n: 


。 在 常量 时 间 内 使 用 底层 数据 结构 是 可 能 的 一 一 例如 ， 


ImmutableSet.copyOf(ImmutableList) 就 不 能 在 常量 时 间 内 完成 。 

。 不 会 造成 内 存 泄露 一 一 例如 ， 你 有 个 很 大 的 不 可 变 集 合 ImmutableList<String> 
hugeList, ImmutableList.copyOf(hugeList.subList(0, 10)) 就 会 显 式 地 拷贝 ， 
以 免 不 必 要 地 持 有 hugeList 的 引用 。 

e 不 改变 语义 一 一 所 以 ImmutableSet.copyOf(mylmmutableSortedSet) 会 显 式 地 
拷贝 ， 因 为 和 基于 比较 器 的 ImmutableSortedSet 相 比 ，ImmutableSet 对 
hashCode() 和 equals 有 不 同 语义 。 


在 可 能 的 情况 下 避免 线性 拷贝 ， 可 以 最 大 限度 地 减少 防御 性 编程 风格 所 带 来 的 性 能 
开销 。 


asList 视 


所 有 不 可 交集 合 都 有 一 个 asList() 方 法 提供 ImmutableList 视 图 ， 来 帮助 你 用 列表 形 
式 方 便 地 读 取 集合 元 素 。 例 如 ， 你 可 以 使 用 sortedSet.asList().get(k) 从 
ImmutableSortedSet 中 读 取 第 k 个 最 小 元 素 。 


asList() 返 回 的 ImmutableList 通 常 是 一 一 并 不 总 是 一 一 开销 稳定 的 视图 实现 ， 而 不 
是 简单 地 把 元 素 拷贝 进 List。 也 就 是 说 ，asList 返 回 的 列表 视图 通常 比 一 般 的 列表 和 平 
均 性 能 更 好 ， 比 如 ， 在 底层 集合 支持 的 情况 下 ， 它 总 是 使 用 高 效 的 contains 方 法 。 





细节 : 关联 可 变 集合 和 不 可 变 集合 


Google Guava 中 文教 程 


属于 *JDK 
可 变 集 合 接口 还 不 可 变 版 本 

是 Guava** 
Collection JDK ImmutableCollection 
List JDK ImmutableList 
Set JDK ImmutableSet 
SortedSet/NavigableSet JDK ImmutableSortedSet 
Map JDK ImmutableMap 
SortedMap JDK ImmutableSortedMap 
Multiset Guava ImmutableMultiset 
SortedMultiset Guava ImmutableSortedMultiset 
Multimap Guava ImmutableMultimap 
ListMultimap Guava ImmutableListMultimap 
SetMultimap Guava ImmutableSetMultimap 
BiMap Guava ImmutableBiMap 
ClassTolnstanceMap Guava ImmutableClassToInstanceMap 
Table Guava ImmutableTable 


2.1- 不 可 变 集 合 


2.2- 新 集合 类 型 


原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : 丁 一 


Guava 引 入 了 很 多 JDK 没 有 的 、 但 我 们 发 现 明 显 有 用 的 新 集合 类 型 。 这 些 新 类 型 是 
为 了 和 JDK 集 合 框 架 共 存 ， 而 没有 往 JDK 集 合 抽象 中 硬 塞 其 他 概念 。 作 为 一 般 规 
则 ，Guava 集 合 非常 精准 地 遵循 了 JDK 接 口 契约 。 


Multiset 
统计 一 个 词 在 文档 中 出 现 了 多 少 次 ， 传 统 的 做 法 是 这 样 的 : 


Map<String, Integer> counts = new HashMap<String, Integer>(); 
for (String word : words) { 
Integer count = counts.get(word); 
if (count == null) { 
counts.put(word, 1); 
} else { 
counts.put(word, count + 1); 
} 


这 种 写法 很 筑 拙 ， 也 容易 出 错 ， 并 且 不 支持 同时 收集 多 种 统计 信息 ， 如 总 词 数 。 我 
们 可 以 做 的 更 好 。 


Guava 提 供 了 一 个 新 集合 类 型 Multiset， 它 可 以 多 次 添加 相等 的 元 素 。 维 基 百 科 从 
数学 角度 这 样 定义 Multiset : "集合 [set] 概 念 的 延伸 ， 它 的 元 素 可 以 重复 出 现 ... 与 集 
合 [set] 相 同 而 与 元 组 [tuple] 相 反 的 是 ， Multiset 元 素 的 顺序 是 无 关 紧 要 的 Multiset 
{a, a, b} 和 {a, b, a} 是 相等 的 ”。 译 者 注 : 这 里 所 说 的 集合 _ /set 是 数学 上 的 概 
念 ，/Multiset 继 承 自 JDK 中 的 Collection 接 口 ， 而 不 是 Set 接 口 ， 所 以 包含 重复 元 素 并 
没有 违反 原 有 的 接口 契约 。 


可 以 用 两 种 方式 看 待 Multiset : 


。 没有 元 素 顺 序 限制 的 ArrayList<E> 
e Map<E, Integer>， 键 为 元 素 ， 值 为 计数 


Guava 的 Multiset API 也 结合 考虑 了 这 两 种 方式 : 当 把 Multiset 看 成 普通 的 Collection 
时 ， 它 表现 得 就 像 无 序 的 ArrayList : 


add(E) 添 加 单个 给 定 元 素 

iterator() 返 回 一 个 迭代 器 ， 包 含 Multiset 的 所 有 元 素 (包括 重复 的 元 素 ) 
size() 返 回 所 有 元 素 的 总 个 数 ( 包 括 重复 的 元 素 ) 

当 把 Multiset 看 作 Map<E, Integer> 时 ， 它 也 提供 了 符合 性 能 期 望 的 查询 操作 : 


e count(Object) 返 回 给 定 元 素 的 计数 。HashMultiset.count 的 复 灯 度 为 O(1)， 





TreeMultiset.count 的 复杂 度 为 O(log n). 
entrySet() 返 回 Set<Multiset.Entry<E>>， 和 Map 的 entrySet 类 似 。 
elementSet() 返 回 所 有 不 重复 元 素 的 Set<E>， 和 Map 的 keySet() 类 似 。 
e 所 有 Multiset 实 现 的 内 存 消耗 随 着 不 重复 元 素 的 个 数 线性 增长 。 


值得 注意 的 是 ， 除 了 极 少 数 情况 ，Multiset 和 JDK 中 原 有 的 Collection 接 口 契 约 完 全 
一 致 一 一 具体 来 说 ，TreeMultiset 在 判断 元 素 是 否 相 等 时 ， 和 与 TreeSet 一 样 用 
compare， 而 不 是 Object.equals。 另 外 特别 注意 ，Multiset.addAlI(Collection) 可 以 
添加 Collection 中 的 所 有 元 素 并 进行 计数 ， 这 比 用 for 循 环 往 Map 添 加 元 素 和 计数 方 
便 多 了 。 





方法 描述 
count(E) 给 定 元 素 在 Multiset 中 的 计数 


elementSet() ”Multiset 中 不 重复 元 素 的 集合 ， 类 型 为 Set<E> 


和 Map 的 entrySet 类 似 ， 返 回 Set<Multiset.Entry<E>>， 其 中 包 
含 的 Entry 支 持 getElement( 和 getCount() 方 法 


add(E, int) 增加 给 定 元 素 在 Multiset 中 的 计数 


entrySet() 


oe 减少 给 定 元 素 在 Multiset 中 的 计数 


a 设置 给 定 元 素 在 Multiset 中 的 计数 ， 不 可 以 为 负数 


size() 返回 集合 元 素 的 总 个 数 (包括 重复 的 元 素 ) 


Multiset 不 是 Map 


请 注意 ，Multiset<E> 不 是 Map<E, Integer>， 虽 然 Map 可 能 是 某 些 Multiset 实 现 的 一 
部 分 。 准 确 来 说 Multiset 是 一 种 Collection 类 型 ， 并 履行 了 Collection 接 口 相 关 的 契 
约 。 关 于 Multiset 和 Map 的 显著 区 别 还 包括 : 


e Multiset 中 的 元 素 计 数 只 能 是 正 数 。 任 何 元 素 的 计数 都 不 能 为 负 ， 也 不 能 是 0。 
elementSet() 和 entrySet() 视 图 中 也 不 会 有 这 样 的 元 素 。 

e multiset.size() 返 回 集合 的 大 小 ， 等 同 于 所 有 元 素 计数 的 总 和 。 对 于 不 重复 元 素 
的 个 数 ， 上 应 使 用 elementSet().size() 方 法 。 (因此 ，add(E) 把 multiset.size() 增 
加 1) 

e multiset.iterator() 会 迭代 重复 元 素 ， 因 此 迭代 长 度 等 于 multiset.size()。 

Multiset 支 持 直 接 增 加 、 减 少 或 设置 元 素 的 计数 。setCount(elem, 0) 等 同 于 移 除 

所 有 elem。 

e 对 multiset 中 没有 的 元 素 ，multiset.count(elem) 始 终 返 回 0。 


Multiset 的 各 种 实现 


Guava 提 供 了 多 种 Multiset 的 实现 ， 大 致 对 应 JDK 中 Map 的 各 种 实现 : 


Map 对 应 的 **Multiset** 是 否 支持 *null* 元 素 
HashMap HashMultiset 是 

TreeMap TreeMultiset ee aa 
LinkedHashMap LinkedHashMultiset 是 

ConcurrentHashMap ConcurrentHashMultiset ， 人 否 

ImmutableMap ImmutableMultiset a 


SortedMultiset 


SortedMultiset#Multiset 接口 的 变种 ， 它 支持 高 效 地 获取 指定 范围 的 子 集 。 比 方 
说 ， 你 可 以 用 latencies.subMultiset(0,BoundType.CLOSED, 100, 
BoundType.OPEN).size() 来 统计 你 的 站 点 中 延迟 在 100 毫 秒 以 内 的 访问 ， 然 后 把 这 
个 值 和 latencies.size() 相 比 ， 以 获取 这 个 延迟 水 平 在 总 体 访问 中 的 比例 。 


TreeMultiset 实 现 SortedMultiset 接 口 。 在 撰写 本 文档 时 ，ImmutableSortedMultiset 
还 在 测试 和 GWT 的 兼容 性 。 


Multimap 


每 个 有 经 验 的 Java 程 序 员 都 在 某 处 实现 过 Map<K, List<V>> 或 Map<K, Set<V>>， 

并 且 要 忍受 这 个 结构 的 笨拙 。 例 如 ，Map<K, Set<V>> 通 常用 来 表示 非 标 定 有 向 
图 。 Guava 的 Multimap 可 以 很 容易 地 把 一 个 键 映 射 到 多 个 值 。 换 句 话说 ，Multimap 
是 把 键 映射 到 任意 多 个 值 的 一 般 方 式 。 


可 以 用 两 种 方式 思考 Multimap 的 概念 : " 键 -单个 值 映 射 "的 集合 : 


a ee day => 20a >4b ==] 3 ce >5 


或 者 " 键 - 值 集合 映射 "的 映射 : 
foes (i 2, 2p ee eee S 
一 般 来 说 ，Multimap 接 口 应 该 用 第 一 种 方式 看 待 ， 但 asMap() 视 图 返回 Map<kK,， 


Collection<V>>， 让 你 可 以 按 另 一 种 方式 看 待 Multimap。 重 要 的 是 ， 不 会 有 任何 键 
映射 到 空 集合 : 一 个 键 要 么 至 少 到 一 个 值 ， 要 么 根本 就 不 在 Multimap 中 。 


很 少 会 直接 使 用 Multimap 接 口 ， 更 多 时 候 你 会 用 ListMultimap 或 SetMultimap 接 口 ， 
它们 分 别 把 键 映射 到 List 或 Set。 


修改 Multimap 


Multimap.get(key) 以 集合 形式 返回 键 所 对 应 的 值 视图 ， 即 使 没有 任何 对 应 的 值 ， 也 


会 返回 空 集合 
对 值 视图 集合 进行 


合 。ListMultimap.get(key) 返 回 List，SetMultimap.get(key) 返 回 Set。 
的 修改 最 终 都 会 反映 到 底层 的 Multimap。 例 如 : 


Set<Person> aliceChildren = childrenMultimap.get(alice); 
aliceChildren.clear(); 
aliceChildren.add(bob) ; 
aliceChildren.add(carol); 


其 他 (更 直接 地 ) 修改 Multimap 的 方法 有 : 


方法 签名 
put(K, V) 


putAll(K, 
Iterable<V>) 


remove(K, V) 


removeAll(K) 


replaceValues(K, 


Iterable<V>) 


Multimap 的 视图 


描述 


添加 键 至 单个 值 的 
映射 


依 Ra WN 条 加 键 到 
值 的 映射 


移 除 键 到 值 的 映 
射 ; 如 果 有 这 样 的 
键 值 并 成 功 移 除 ， 
返回 true。 


清除 键 对 应 的 所 有 
值 ， 返 回 的 集合 包 
Meira 
的 值 ， 但 修改 这 
集合 就 不 会 影响 
Multimap 了 。 


清除 键 对 应 的 所 有 
值 ， 并 重新 把 key 关 
联 到 lterable 中 的 每 
个 元 素 。 返 回 的 集 
合 包含 所 有 之 前 映 
射 到 K 的 值 。 


Multimap 还 支持 若干 强大 的 视图 : 


e asMap 为 Multimap<K, V> 提 供 Map<K,Collection<V>> 形 式 的 视图 。 


等 价 于 
multimap.get(key).add(value) 


Iterables.addAll(multimap.get(key), 
values) 


multimap.get(key).remove(value) 


multimap.get(key).clear() 


multimap.get(key).clear(); 
Iterables.addAll(multimap.get(key), 
values) 


返回 的 


Map 支 持 remove 操 作 ， 并 且 会 反映 到 底层 的 Multimap， 但 它 不 支持 put 或 putAll 


操作 。 更 重要 的 是 ， 如 果 你 想 为 Multimap 中 没有 的 键 返回 null, 
， 你 就 可 以 使 用 asMap().get(key)。 
asMap.get(key) 返 回 的 结果 转化 为 适当 的 集合 类 型 
SetMultimap.asMap.get(key) 的 结果 转 为 Set， 


的 、 可 写 的 空 集合 


而 不 是 一 个 新 
(你 可 以 并 且 应 当 把 
如 





ListMultimap.asMap.get(key) 的 


结果 转 为 List ”Java 类 型 系统 不 允许 ListMultimap 直 接 为 asMap.get(key) 返 回 
List 一 一 译 者 注 : 也 可 以 用 /Multimaps 中 的 asMap 静 态 方法 帮 你 完成 类 型 转 
换 ) 

entries 用 Collection<Map.Entry<K, V>> 返 回 Multimap 中 所 有 ” 键 -单个 值 映 
射 一 包括 重复 键 。 (对 SetMultimap， 返 回 的 是 Set) 

keySet 用 Set 表 示 Multimap 中 所 有 不 同 的 键 。 

keys 用 Multiset 表 示 Multimap 中 的 所 有 键 ， 每 个 键 重复 出 现 的 次 数 等 于 它 映 
射 的 值 的 个 数 。 可 以 从 这 个 Multiset 中 移 除 元 素 ， 但 不 能 做 添加 操作 ; 移 除 操 
作 会 反映 到 底层 的 Multimap。 

values() 用 一 个 ”局 平 " 的 Collection<V> 包 含 Multimap 中 的 所 有 值 。 这 有 一 点 
类 似 于 lterables.concat(multimap.asMap().values())， 但 它 直接 返回 了 单个 
Collection， 而 不 像 multimap.asMap().values() 那 样 是 按键 区 分 开 的 
Collection。 








Multimap 不 是 Map 


Multimap<K, V> 不 是 Map<K,Collection<V>>， 虽 然 某 些 Multimap 实 现 中 可 能 使 用 
了 map。 它 们 之 间 的 显著 区 别 包括 : 


Multimap.get(key) 总 是 返回 非 null、 但 是 可 能 空 的 集合 。 这 并 不 意味 着 
Multimap 为 相应 的 键 花费 内 存 创建 了 集合 ， 而 只 是 提供 一 个 集合 视图 方便 你 为 
键 增加 映射 值 一 一 译 者 注 : 如 果 有 这 样 的 键 ， 返 回 的 集合 只 是 包装 了 

_ Muwimap 中 已 有 的 集合 ; 如 果 没 有 这 样 的 键 ， 返 回 的 空 集合 也 只 是 持 有 
Multimap 引 用 的 栈 对 象 ， 让 你 可 以 用 来 操作 底层 的 Multimap。 因 此 ， 返 回 的 集 
合 不 会 占据 太 多 内 存 ， 数 据 实际 上 还 是 存放 在 Multimap 中 。 

如 果 你 更 喜欢 像 Map 那 样 ， 为 Multimap 中 没有 的 键 返回 null， 请 使 用 asMap() 视 
图 获取 一 个 Map<K, Collection<V>>。 (或 者 用 静态 方法 Multimaps.asMap() 为 
ListMultimap 返 回 一 个 Map<K, List<V>>。 对 于 SetMultimap 和 
SortedSetMultimap， 也 有 类 似 的 静态 方法 存在 ) 

当 且 仅 当 有 值 映射 到 键 时 ，Multimap.containsKey(key) 才 会 返回 true。 尤 其 需 
要 注意 的 是 ， 如 果 键 k 之 前 映射 过 一 个 或 多 个 值 ， 但 它们 都 被 移 除 后 ， 
Multimap.containsKey(key) 会 返回 false。 
Multimap.entries() 返 回 Multimap 中 所 有 " 键 -单个 值 映 射 ' 一 一 包括 重复 键 。 如 果 
你 想 要 得 到 所 有 ” 键 - 值 集合 映射 ”， 请 使 用 asMap().entrySet()。 
Multimap.size() 返 回 所 有 ” 键 -单个 值 映 射 " 的 个 数 ， 而 非 不 同 键 的 个 数 。 要 得 到 
不 同 键 的 个 数 ， 请 改 用 Multimap.keySet().size()。 





Multimap 的 各 种 实现 


Multimap 提 供 了 多 种 形式 的 实现 。 在 大 多 数 要 使 用 Map<K, Collection<V>> 的 地 


J; 


你 都 可 以 使 用 它们 : 


实现 

ArrayListMultimap 

HashMultimap 

LinkedListMultimap* 

LinkedHashMultimap** 

TreeMultimap 
ImmutableListMultimap 


ImmutableSetMultimap 


键 行为 类 似 
HashMap 
HashMap 
LinkedHashMap* 
LinkedHashMap 
TreeMap 
ImmutableMap 


ImmutableMap 


值 行为 类 似 
ArrayList 
HashSet 
LinkedList* 
LinkedHashMap 
TreeSet 
ImmutableList 


ImmutableSet 


除了 两 个 不 可 变形 式 的 实现 ， 其 他 所 有 实现 都 支持 null 键 和 null 值 
*LinkedListMultimap.entries() 保 留 了 所 有 键 和 值 的 迭代 顺序 。 详 情 见 doc 链 接 。 


**LinkedHashMultimap 保 留 了 映射 项 的 插入 顺序 ， 包 括 键 插入 的 顺序 ， 以 及 键 映 射 


的 所 有 值 的 插入 顺序 。 


请 注意 ， 并 非 所 有 的 Multimap 都 和 上 面 列 出 的 一 样 ， 使 用 Map<K, Collection<V>> 


来 实现 (特别 是 ， 一 些 Multimap 实 现 用 了 自 定义 的 hashTable， 以 最 小 化 开销 ) 


如 果 你 想 要 更 大 的 定制 化 ， 请 用 Multimaps.newMultimap(Map， 
Supplier<Collection>) 或 list 和 set 版 本 ， 使 用 自 定义 的 Collection、List 或 Set 实 现 


Multimap。 


BiMap 


传统 上 ， 实 现 键 值 对 的 双向 映射 需要 维护 两 个 单独 的 map， 并 保持 它们 间 的 同步 。 
但 这 种 方式 很 容易 出 错 ， 而 且 对 于 值 已 经 在 map 中 的 情况 ， 会 变 得 非常 混乱 。 例 


如 : 


Map<String, Integer> nameToId 
Map<Integer, String> idToName 


nameToId.put("Bob", 42); 
idToName.put(42, "Bob"); 


// 如 果 "Bob" 和 42 已 经 在 map 中 了 ， 会 发 生 什么 ? 
// 如 果 我 们 忘 了 同步 两 个 map， 会 有 诡异 的 bug 发 生 ..， 


BiMap<K, V> 是 特殊 的 Map : 


e 可 以 用 inverse() 反 转 BiMap<K, V> 的 键 值 映 射 
e 保证 值 是 唯一 的 ， 因 此 values() 返 回 Set 而 不 是 普通 的 Collection 


Maps.newHashMap(); 
Maps.newHashMap(); 


在 BiMap 中 ， 如 果 你 想 把 键 映射 到 已 经 存在 的 值 ， 会 抛 出 lllegalArgumentException 
异常 。 如 果 对 特定 值 ， 你 想 要 强制 替换 它 的 键 ， 请 使 用 BiMap.forcePut(key, 


value). 


BiMap<String, Integer> userId = HashBiMap.create(); 


String userForId = userId.inverse().get(id); 


BiMap 的 各 种 实现 
键 ” 一 后 值 实现 值 “ 一 关键 实现 对 应 的 *BiMap* 实 现 
HashMap HashMap HashBiMap 
ImmutableMap ImmutableMap ImmutableBiMap 
EnumMap EnumMap EnumBiMap 
EnumMap HashMap EnumHashBiMap 


È : Maps 类 中 还 有 一 些 诸如 synchronizedBiMap 的 BiMap 工 具 方 法 . 


Table 


Table<Vertex, Vertex, Double> weightedGraph = HashBasedTable.create 
weightedGraph.put(vi, v2, 4); 
weightedGraph.put(vi, v3, 20); 
weightedGraph.put(v2, v3, 5); 


weightedGraph.row(v1); // returns a Map mapping v2 to 4, v3 to 20 
weightedGraph.column(v3); // returns a Map mapping vi to 20, v2 to 


通常 来 说 ， 当 你 想 使 用 多 个 键 做 索引 的 时 候 ， 你 可 能 会 用 类 似 Map<FirstName,， 
Map<LastName, Person>> 的 实现 ， 这 种 方式 很 了 丑陋 ， 使 用 上 也 不 友好 。Guava 为 
此 提供 了 新 集合 类 型 Table， 它 有 两 个 支持 所 有 类 型 的 键 : " 行 "和 ” 列 "。Table 提 供 多 
种 视图 ， 以 便 你 从 各 种 角度 使 用 它 : 


e rowMap() : 用 Map<R, Map<C, V>> 表 现 Table<R, C, V>。 同 样 的 ， 
rowKeySet() 返 回 ” 行 ”的 集合 Set<R>。 

e row(r) : 用 Map<C, V> 返 回 给 定 ” 行 "的 所 有 列 ， 对 这 个 map 进 行 的 写 操作 也 将 
写 入 Table 中 。 

e 类 似 的 列 访问 方法 : columnMap()、columnKeySet()、column(c)。 (基于 列 的 
访问 会 比 基 于 的 行 访问 稍微 低 效 点 ) 

。cellSet() : 用 元 素 类 型 为 Table.Cell<R, C, V> 的 Set 表 现 Table<R, C, V>, Cell 





类 似 于 Map.Entry， 但 它 是 用 行 和 列 两 个 键 区 分 的 。 
Table 有 如 下 几 种 实现 : 


e HashBasedTable : 本 质 上 用 HashMap<R, HashMap<C, V>> 实 现 ; 

e TreeBasedTable : 本 质 上 用 TreeMap<R, TreeMap<C,V>> 实 现 ; 

e ImmutableTable : 本 质 上 用 ImmutableMap<R, ImmutableMap<C, V>> 实 现 ; 
注 : ImmutableTable 对 稀 玻 或 密集 的 数据 集 都 有 优化 。 

e ArrayTable : 要 求 在 构造 时 就 指定 行 和 列 的 大 小 ， 本 质 上 由 一 个 二 维 数组 实 
现 ， 以 提升 访问 速度 和 密集 Table 的 内 存 利用 率 。ArrayTable 与 其 他 Table 的 工 
作 原 理 有 点 不 同 ， 请 参见 Javadoc 了 解 详 情 。 


ClassTolnstanceMap 
ClassTolnstanceMap 是 一 种 特殊 的 Map : 它 的 键 是 类 型 ， 而 值 是 符合 键 所 指 类 型 的 
对 象 。 


为 了 扩展 Map 接 口 ，ClassTolnstanceMap 人 额外 声明 了 两 个 方法 :T 
getlnstance(Class<T>) 和 T putlnstance(Class<T>, T)， 从 而 避免 强制 类 型 转换 ， 
同时 保证 了 类 型 安全 。 


ClassTolnstanceMap 有 了 唯一 的 泛 型 参数 ， 通 常 称 为 B， 代 表 Map 支 持 的 所 有 类 型 的 
上 界 。 例 如 : 


ClassToInstanceMap<Number> numberDefaults=MutableClassToInstanceMay 
numberDefaults.putInstance(Integer.class, Integer.valueOf(0)); 


re 


MRE, ClassTolnstanceMap<B> #1, 7 Map<Class<? extends B>, B> 





或 
者 换 名 话说 ， 是 一 个 映射 B 的 子 类 型 到 对 应 实例 的 Map。 这 让 ClassTolnstanceMap 
包含 的 泛 型 声明 有 点 售 人 困惑 ， 但 请 记 住 B 始 终 是 Map 所 支持 类 型 的 上 界 一 “通常 B 
就 是 Object。 





对 于 ClassTolnstanceMap，Guava 提 供 了 两 种 有 用 的 实 
现 : MutableClassTolnstanceMap 和 ImmutableClassTolnstanceMap。 


RangeSet 


RangeSet 描 述 了 一 组 不 相连 的 、 非 空 的 区 间 。 当 把 一 个 区 间 添 加 到 可 变 的 
RangeSet 时 ， 所 有 相连 的 区 间 会 被 合并 ， 空 区 间 会 被 忽略 。 例 如 : 


RangeSet<Integer> rangeSet = TreeRangeSet.create(); 
rangeSet.add(Range.closed(1, 10)); // {[1,10]} 
rangeSet.add(Range.closedOpen(11, 15));//##82##K iq: {[1,10], [11,15) 
rangeSet.add(Range.closedOpen(15, 20)); // 相 连 区 间 ; {[1,10], [11,20) 
rangeSet.add(Range.openClosed(0, 0)); // 空 区 间 ; {[1,10], [11,20)} 
rangeSet.remove(Range.open(5, 10)); // 分 割 [1，10]; {[1,5], [10,10], 








请 注意 ， 要 合并 Range.closed(1, 10) 和 Range.closedOpen(11, 15) 这 桩 的 区 间 ， 你 
需要 首先 用 Range.canonical(DiscreteDomain) 对 区 间 进 行 预 处 理 ， 例 如 
DiscreteDomain.integers(). 


注 : RangeSet 不 支持 GWT， 也 不 支持 JDK5 和 更 早 版 本 ; 因为 ，RangeSet 需 要 充 
分 利用 JDK6 中 NavigableMap 的 特性 。 


RangeSet 的 视 
RangeSet 的 实现 支持 非常 广泛 的 视图 : 


e complement() : 返回 RangeSet 的 补 集 视图 。complement 也 是 RangeSet 类 型 ， 
包含 了 不 相连 的 、 非 空 的 区 间 。 

e subRangeSet(Range<C>) : 返回 RangeSet 与 给 定 Range 的 交集 视图 。 这 扩展 
了 传统 排序 集合 中 的 headSet、subSet 和 tailSet 操 作 。 

e asRanges() : 用 Set<Range<C>> 表 现 RangeSet， 这 样 可 以 通 历 其 中 的 
Range。 

e asSet(DiscreteDomain<C>) ( 仅 lImmutableRangeSet 支 持 ) : 用 
ImmutableSortedSet<C> 表 现 RangeSet， 以 区 间 中 所 有 元 素 的 形式 而 不 是 区 
间 本 身 的 形式 查看 。 (这 个 操作 不 支持 DiscreteDomain 和 RangeSet 都 没有 上 
边界 ， 或 都 没有 下 边界 的 情况 ) 


RangeSet 的 查询 方法 


为 了 方便 操作 ，RangeSet 直 接 提供 了 若干 查询 方法 ， 其 中 最 突出 的 有 : 
e contains(C) : RangeSet 最 基本 的 操作 ， 判 断 RangeSet 中 是 否 有 任何 区 间 包 含 


给 定 元 素 。 
e rangeContaining(C) : 返回 包含 给 定 元 素 的 区 间 ; 若 没 有 这 样 的 区 间 ， 则 返回 
null, 


e encloses(Range<C>) : 简单 明了 ， 判 断 RangeSet 中 是 否 有 任何 区 间 包 括 给 定 
区 间 。 
e span() : 返回 包括 RangeSet 中 所 有 区 间 的 最 小 区 间 。 


RangeMap 


RangeMap 描 述 了 ”不 相交 的 、 非 空 的 区 闻 "到 特定 值 的 映射 。 和 RangeSet 不 同 ， 
RangeMap 不 会 合并 相 邻 的 映射 ， 即 便 相 邻 的 区 间 了 映射 到 相同 的 值 。 例 如 : 


RangeMap<Integer, String> rangeMap = TreeRangeMap.create(); 
rangeMap.put(Range.closed(1, 10), "foo"); //{[1,10] => "foo"} 
rangeMap.put(Range.open(3, 6), "bar"); //{[1,3] => "foo", (3,6) => 
rangeMap.put(Range.open(10, 20), "foo"); //{[1,3] => "foo", (3,6) =: 
rangeMap.remove(Range.closed(5, 11)); //{[1,3] => "foo", (3,5) => ' 


«| = >| 








RangeMap 的 视 
RangeMap 提 供 两 个 视图 : 


e asMapOfRanges() : 用 Map<Range<K>, V> 表 现 RangeMap。 这 可 以 用 来 通 历 
RangeMap. 

e subRangeMap(Range<K>) : 用 RangeMap 类 型 返回 RangeMap 与 给 定 Range 
的 交集 视图 。 这 扩展 了 传统 的 headMap、subMap 和 tailMap 操 作 。 


2.3- 强 大 的 集合 工具 类 : java.util.Collections 中 未 
包含 的 集合 工具 


原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : 丁 一 
尚未 完成 : Queues, Tables 工 具 类 


任何 对 JDK 集 合 框架 有 经 验 的 程序 员 都 熟悉 和 喜欢 java.util.collection 包含 
的 工具 方法 。 Guava 治 着 这 些 路 线 提供 了 更 多 的 工具 方法 : 适用 于 所 有 集合 的 静态 
方法 。 这 是 Guava 最 流行 和 成 熟 的 部 分 之 一 。 


我 们 用 相对 直观 的 方式 把 工具 类 与 特定 集合 接口 的 对 应 关系 为 纳 如 下 : 


集合 接口 Bion 对 应 的 wGuava** 工 具 类 
elein |. aah java.st Colections#238 
List JDK Lists 

Set JDK Sets 

SortedSet JDK Sets 

Map JDK Maps 

SortedMap JDK Maps 

Queue JDK Queues 

Multiset Guava Multisets 

Multimap Guava Multimaps 

BiMap Guava Maps 

Table Guava Tables 


在 找 类 似 转化 、 过 滤 的 方法 ? EROS, MARU. 
静态 工厂 方法 
在 JDK 7 之 前 ， 构 造 新 的 范 型 集合 时 要 讨厌 地 重复 声明 范 型 : 


List<TypeThatsTooLongForItsOwnGood> list = new ArrayList<TypeThatS- 
‘| — # žo] 








我 想 我 们 都 认为 这 很 讨厌 。 因 此 Guava 提 供 了 能 够 推断 范 型 的 静态 工厂 方法 : 


List<TypeThatsTooLongForItsOwnGood> list = Lists.newArrayList(); 
Map<KeyType, LongishValueType> map = Maps.newLinkedHashMap(); 


可 以 肯定 的 是 ，JDK7 版 本 的 钻石 操作 符 (<>) 没 有 这 样 的 麻烦 : 


List<TypeThatsTooLongForItsOwnGood> list = new ArrayList<>(); 


但 Guava 的 静态 工厂 方法 远 不 止 这 么 简单 。 用 工厂 方法 模式 ， 我 们 可 以 方便 地 在 初 
始 化 时 就 指定 起 始 元 素 。 


Set<Type> copySet = Sets.newHashSet(elements) ; 
List<String> theseElements = Lists.newArrayList("alpha", "beta", "ç 
1 


此 外 ， 通 过 为 工厂 方法 命名 (Effective Java 第 一 条 ) ， 我 们 可 以 提高 集合 初始 化 大 
小 的 可 读 性 : 





List<Type> exactly100 = Lists.newArrayListWithCapacity(100) ; 
List<Type> approx100 = Lists.newArrayListWithExpectedSize(100); 
Set<Type> approxi100Set = Sets.newHashSetWithExpectedSize(100); 


确切 的 静态 工厂 方法 和 相应 的 工具 类 一 起 罗列 在 下 面 的 章节 。 


注意 : Guava 引 和 的 新 集合 类 型 没有 暴露 原始 构造 器 ， 也 没有 在 工具 类 中 提供 初始 
化 方法 。 而 是 直接 在 集合 类 中 提供 了 静态 工厂 方法 ， 例 如 : 


Multiset<String> multiset = HashMultiset.create(); 


Iterables 


在 可 能 的 情况 下 ，Guava 提 供 的 工具 方法 更 偏向 于 接受 lterable 而 不 是 Collection 类 
型 。 在 Google， 对 于 不 存放 在 主 存 的 集合 一 一 比如 从 数据 库 或 其 他 数据 中 心 收集 的 
结果 集 ， 因 为 实际 上 还 没有 氛 取 全 部 数据 ， 这 类 结果 集 都 不 能 支持 类 似 size() 的 操 
作 一 一 通常 都 不 会 用 Collection 类 型 来 表示 。 


因此 ， 很 多 你 期 望 的 支持 所 有 集合 的 操作 都 在 Iterables 类 中 。 大 多 数 lterables 
方法 有 一 个 在 lterators 类 中 的 对 应 版 本 ， 用 来 处 理 lterator。 


截至 Guava 1.2 版 本 ，lterables 使 
用 [FluentIterable](http://docs.guava-libraries.googlecode.com/git -h: 
进行 了 补充 ， 它 包装 了 一 个 lterable 实 例 ， 并 对 许多 操作 提供 了 ”fluent”( 链 式 调 


用 ) 语法 。 
下 面 列 出 了 一 些 最 常用 的 工具 方法 ， 但 更 多 |terables 的 函数 式 方法 将 在 第 四 章 讨 


论 。 
常规 方法 


串联 多 个 iterables 的 懒 视 
图 * 


返回 对 象 在 iterable 中 出 现 
的 次 数 Coll 


把 iterable 按 指 网 
partition(Iterable, int) 割 ， 得 到 的 子 集 都 不 能 List: 
行 修改 操作 


返回 iterable 的 第 一 
getFirst(Iterable, T default) 3%, Fiterablex Z o 返回 与 ltera 
默认 值 


返回 iterable 的 最 后 一 个 元 
getLast(Iterable) 素 ， 若 iterable 为 空 则 抛 出 getLé 
NoSuchElementException 


concat (Iterable&lt;Iterableéggt; ) conci 


frequency(Iterable, Object) 


FluentIterable.last() || elementsEqual(Iterable, Iterable) | MRA 
个 iterable 中 的 所 有 元 素 相等 且 顺 序 一 致 ， 返 回 true | SList.equals(Object) rb 4 | | 
unmodifiableIterable(Iterable) | 返回 iterable 的 不 可 变 视 图 | 与 Collections. 
unmodifiableCollection(Collection) 比 较 || limit(Iterable, int) | 限制 iterable 
的 元 素 个 数 限制 给 定 值 | FluentIterable.limit(int) || 
getOnlyElement(Iterable) | 获取 iterable 中 唯一 的 元 素 ， 如 果 iterable 为 空 或 有 
多 个 元 素 ， 则 快速 失败 | getOnlyElement(Iterable, T default) | 


* 译 者 注 : 懒 视图 意味 着 如 果 还 没 访问 到 某 个 jterable 中 的 元 素 ， 则 不 会 对 它 进行 串 
联 操作 。 


Iterable<Integer> concatenated = Iterables.concat( 

Ints.asList(1, 2, 3), 

Ints.asList(4, 5, 6)); // concatenated 包 括 元 素 1，2, 3, 4, 5 
String lastAdded = Iterables.getLast(myLinkedHashSet ) ， 
String theElement = Iterables.getOnlyElement(thisSetIsDefinitelyAs: 
// 如 果 set 不 是 单元 素 集 ， 就 会 出 错 了 |! 


= 


与 Collection 方 法 相似 的 工具 方法 
通常 来 说 ，Collection 的 实现 天 然 支持 操作 其 他 Collection， 但 却 不 能 操作 lterable。 





下 面 的 方法 中 ， 如 果 传 和 的 lterable 是 一 个 Collection 实 例 ， 则 实际 操作 将 会 委托 给 
相应 的 Collection 接 口 方 法 。 例 如 ， 往 lterables.size 方 法 传人 是 一 个 Collection 实 


例 ， 它 不 会 真 的 通 历 iterator 获 取 大 小 ， 而 是 直接 调用 Collection.size。 


方法 

addAll(Collection addTo, Iterable toAdd) 
contains(Iterable, Object) 

removeAll(Iterable removeFrom, Collection toRemove) 
retainAll(Iterable removeFrom, Collection toRetain) 
size(Iterable) 

toArray(Iterable, Class) 

isEmpty(Iterable) 


get(Iterable, int) 


KALB Colle 
Collection.ad: 
Collection.co! 
Collection.rer 
Collection.ret 
Collection.siz 
Collection.to/ 
Collection.isE 


List.get(int) 


toString(Iterable) Collection.tos 
Fluentiterable 
除了 上 面 和 第 四 章 提 到 的 方法 ，Fluentlterable 还 有 一 些 便利 方法 用 来 把 自己 拷贝 到 
不 可 变 集合 

ImmutableList 

ImmutableSet toImmutableSet() 

ImmutableSortedSet toImmutableSortedSet (Comparator ) 
Lists 
除了 静态 工厂 方法 和 画 数 式 编 程 方法 ， Lists 为 List 类 型 的 对 象 提供 了 若干 工具 方 
法 。 

方法 描述 


partition(List, int)  ， 把 List 按 指定 大 小 分 荐 


reverse(List) 


返回 给 定 List 的 反 转 视图 。 注 : 如 果 List 是 不 可 变 
的 ， 考 虑 改 用 ImmutableList.reverse() 。 


List countUp = Ints.asList(1, 2, 3, 4, 5); 
List countDown = Lists.reverse(theList); // {5, 4, 3, 2, 1} 
List<List> parts = Lists.partition(countUp, 2);//{{1,2}, {3,4}, {5. 


4. _ = _ ES 


静态 工厂 方法 
Lists 提 供 如 下 静态 工厂 方法 : 














具体 实现 、 
天 型 > | 工厂 方法 


basic, with elements, from Iterable , with exact capacity, with 


PRA YES expected size, from Iterator 


LinkedList basic, from Iterable 


Sets 
Sets 工具 类 包含 了 若干 好 用 的 方法 。 
集合 理论 方法 


我 们 提供 了 很 多 标准 的 集合 运算 (Set-Theoretic) 方法 ， 这 些 方法 接受 Set 参 数 并 
返回 SetView ， 可 用 于 : 


。 直接 当 作 Set 使 用 ， 因 为 SetView 也 实现 了 Set 接 口 ; 
e 用 copyInto(Set) 拷贝 进 另 一 个 可 变 集 合 ; 

e 用 immutableCopy() 对 自己 做 不 可 变 拷 贝 。 

方法 

union(Set, Set) 

intersection(Set, Set) 

difference(Set, Set) 


symmetricDifference(Set, Set) 


使 用 范例 : 


Set<String> wordswithPrimeLength = ImmutableSet.of("one", "two", "i 
Set<String> primes = ImmutableSet.of("two", "three", "five", "sever 
SetView<String> intersection = Sets.intersection(primes,wordswithP! 
// intersection@S"two", "three", "seven" 

return intersection,.immutablecopy(),;/V/ 可 以 使 用 交集 ， 但 不 可 变 持 贝 的 读 取 效 








‘| =a) D 
其 他 Set 工 具 方 法 
方法 i 另 请 参见 
PUA 
WR 
回 
所 
有 
= 
cartesianProduct(List&lt;Set&gt; ) 全 cartesianProduct(Set... 
的 
fA 
卡 
JL 


oh 
bis) 


powerSet (Set) 


aE ON ot SA D> a Plt > TG) fe 


Set<String> animals = ImmutableSet.of("gerbil", "hamster"); 
Set<String> fruits = ImmutableSet.of("apple", "orange", "banana"); 


Set<List<String>> product = Sets.cartesianProduct(animals, fruits), 
// {{"gerbil", "apple"}, {"gerbil", "“orange"}, {"gerbil", "banana" 
// {"hamster", "apple"}, {"hamster", "orange"}, {"hamster", "banar 


Set<Set<String>> animalSets = Sets.powerSet(animals); 
// {{}, {"gerbil"}, {"hamster"}, {"gerbil", "hamster"}} 











静态 工厂 方法 
Sets 提 供 如 下 静态 工厂 方法 : 


具体 实现 类 型 工厂 方法 


basic, with elements, from Iterable ,with expected size, 
from Iterator 


LinkedHashSet basic,from Iterable ,with expected size 


TreeSet basic, with comparator ,from Iterable 


Maps 
Maps 类 有 若干 值得 单独 说 明 的 、 很 酷 的 方法 。 


uniquelndex 


Maps . uniqueIndex(Iterable, Function) 通常 针对 的 场景 是 : 有 一 组 对 象 ， 它 
们 在 某 个 属性 上 分 别 有 独 一 无 二 的 值 ， 而 我 们 希望 能 够 按照 这 个 属性 值 查找 对 象 
译 者 注 : 这 个 方法 返回 一 个 _Map， 键 为 Function 返 回 的 属性 值 ， 值 为 /terable 
中 相应 的 元 素 ， 因 此 我 们 可 以 反复 用 这 个 Map 进 行 查找 操作 。 


比方 说 ， 我 们 有 一 堆 字 符 串 ， 这 些 字符 串 的 长 度 都 是 独一无二 的 ， 而 我 们 希望 能 够 
按照 特定 长 度 查找 字符 串 : 





ImmutableMap<Integer, String> stringsByIndex = Maps.uniqueIndex(sti 
new Function<String, Integer> () { 
public Integer apply(String string) { 
return string.length(); 





如 果 索 引 值 不 是 独一无二 的 ， 请 参见 下 面 的 Multimaps.index 方 法 。 


difference 


Maps.difference(Map，Map) 用 来 比较 两 个 Map 以 获取 所 有 不 同 点 。 该 方法 返回 
MapDifference 对 象 ， 把 不 同 点 的 维 恩 图 分 解 为 : 


entriesInCommon( ) 两 个 Map 中 都 有 的 映射 项 ， 包 括 匹 配 的 键 与 值 


键 相 同 但 是 值 不 同 值 映 射 项 。 返 回 的 Map 的 值 类 
entriesDiffering() 型 为 MapDifference.ValueDifference , LAR 
示 左 右 两 个 不 同 的 值 


entriesOnlyOnLeft() 键 只 存在 于 左边 Map 的 映射 项 
entriesonlyOnRight() 键 只 存在 于 右边 Map 的 映射 项 


Map<String, Integer> left = ImmutableMap.of("a", 1, "b", 2, "c", 3 
Map<String, Integer> left = ImmutableMap.of("a", 1, "b", 2, "c", 3 
MapDifference<String, Integer> diff = Maps.difference(left, right), 


diff.entriesInCommon(); // {"b" => 2} 
diff.entriesInCommon(); // {"b" => 2} 


diff.entriesOnlyOnLeft(); // {"a" => 1} 
diff.entriesOnlyOnRight(); // {"d" => 5} 


4 ay 
义理 BiMap 的 工具 方法 


Guava 中 处 理 BiMap 的 工具 方法 在 Maps 类 中 ， 因 为 BiMap 也 是 一 种 Map 实 现 。 





BiMap* 工 具 方 法 ** 相应 的 Map* 工 具 方 法 
synchronizedBiMap(BiMap) Collections.synchronizedMap(Map) 
unmodifiableBiMap(BiMap) Collections.unmodifiableMap(Map) 
MALT Aik 
Maps 提 供 如 下 静态 工厂 方法 : 
具体 实现 类 型 工厂 方法 
HashMap basic, from Map , with expected size 
LinkedHashMap basic, from Map 
basic, from Comparator , from 
TreeMap SortedMap 
EnumMap from Class ,from Map 


ConcurrentMap : 支持 所 有 操 oe 
iE 


IdentityHashMap basic 


Multisets 


标准 的 Collection 操 作 会 忽略 Multiset 重 复元 素 的 个 数 ， 而 只 关心 元 素 是 否 存在 于 
Multiset 中 ， 如 containsAll 方 法 。 为 此 ， Multisets 提供 了 若干 方法 ， 以 顾及 


Multiset 元 素 的 重复 性 : 


方法 


containsOccurrences(Multiset sup, Multiset sub) 


removeOccurrences(Multiset removeFrom, Multiset toRemove) 


retainOccurrences(Multiset removeFrom, Multiset toRetain) 


intersection(Multiset, Multiset) 


Multiset<String> multiseti = HashMultiset.create(); 
multiseti.add("a", 2); 


Multiset<String> multiset2 = HashMultiset.create(); 
multiset2.add("a", 5); 


说 明 


sÈ 
sub.cc 
<=suc 
回 true 


对 toR 
元 素 ， 

remov 
相同 个 
修改 re 
BUR 
remov 
<=toR 


返回 如 
集 ; 


multiseti.containsAll(multiset2); // 返 回 true ; 因为 包含 了 所 有 不 重复 元 素 ， 


// 虽 然 multiset1 实 际 上 包含 2 个 "a"， 而 multiset2 包 含 5 个 "a" 


Multisets.containsOccurrences(multiseti, multiset2); // returns fai 


multiset2.removeOccurrences(multiset1); // multiset2 现在 包含 3 个 "a" 
multiset2.removeAll(multiset1);//multiset2 移 除 所 有 "a"， 哩 然 hultiset15 


multiset2.isEmpty(); // returns true 
Multisets 中 的 其 他 工具 方法 还 包括 : 





Z] 


A [5] Multisethy # Fy & 
拷贝 ， 并 将 元 素 按 重 


copyHighestCountFirst(Multiset) 复出 现 的 次 数 做 降序 
AWAY 7 TE 


排列 
unmodifiableMultiset (Multiset ) “a 视 
unmodifiableSortedMultiset(SortedMultiset ) pared aca 
只 读 视 图 


Multiset<String> multiset = HashMultiset.create(); 
multiset.add("a", 3); 
multiset.add("b", 5); 
multiset.add("c", 1); 


ImmutableMultiset highestCountFirst = Multisets.copyHighestCountFi) 
//highestCountFirst, @imehWentrySet#elementSet, #{"b", "a", "c"}H 


== 





Multimaps 


Multimaps 提供 了 若干 值得 单独 说 明 的 通用 工具 方法 


index 


作为 Maps.uniqueIndex 的 兄弟 方 

法 ， Multimaps.index(Iterable，Function) 通常 针对 的 场景 是 : 有 一 组 对 
象 ， 它 们 有 共同 的 特定 属性 ， 我 们 希望 按照 这 个 属性 的 值 查询 对 象 ， 但 属性 值 不 一 
定 是 独一无二 的 。 


比方 说 ， 我 们 想 把 字符 串 按 长 度 分 组 。 


ImmutableSet digits = ImmutableSet.of("zero", "one", "two", "three' 
Function<String, Integer> lengthFunction = new Function<String, Ini 
public Integer apply(String string) { 
return string.length(); 
} 


}; 
ImmutableListMultimap<Integer, String> digitsByLength= Multimaps.ir 


is 
i cele erat maps: 


* => {"one", "two", cyl Gal: 

大 => {"zero", "four", "five", "nine"} 
* 5 => {"three", "seven", "eight"} 

*/ 





invertFrom 


鉴于 Multimap 可 以 把 多 个 键 映 射 到 同一 个 值 〈 译 者 注 : 实际 上 这 是 任何 _ map 都 有 
的 特性 ) ， 也 可 以 把 一 个 键 映 射 到 多 个 值 ， 反 转 Multimap 也 会 很 有 用 。Guava 提供 
了 invertFrom(Multimap toInvert, Multimap dest) ) 做 这 个 操作 ， 并 且 你 可 
以 自由 选择 反 转 后 的 Multimap 实 现 。 


注 : 如 果 你 使 用 的 是 ImmutableMultimap， 考 虑 改 
用 ImmutableMultimap.inverse() 做 反 转 。 


ArrayListMultimap<String, Integer> multimap = ArrayListMultimap.cre 
multimap.putAll("b", Ints.asList(2, 4, 6)); 
multimap.putAll("a", Ints.asList(4, 2, 1)); 
multimap.putAll("c", Ints.asList(2, 5, 3)); 


TreeMultimap<Integer, String> inverse = Multimaps.invertFrom(multir 
// 注 意 我 们 选择 的 实现 ， 因 为 选 了 TreeMultimap， 得 到 的 反 转 结果 是 有 序 的 
phe 
* inverse m 
* 1 => 
W bs uae ree. 


My 





想 在 Map 对 象 上 使 用 Multimap 的 方法 吗 ? forMap(Map) 把 Map 包 装 
SetMultimap。 这 个 方法 特别 有 用 ， 例 如 ， 与 Multimaps.invertFrom 结 合 使 用 ， 可 以 
把 多 对 一 的 Map 反 转 为 一 对 多 的 Multimap。 


Map<String, Integer> map = ImmutableMap.of("a", 1, "b", 1, "c", 2), 
SetMultimap<String, Integer> multimap = Multimaps.forMap(map) ; 

// multimap: ["a" => {1}, "b" => {1}, "c" => {2}] 

Multimap<Integer, String> inverse = Multimaps.invertFrom(multimap, 
// inverse: [1 => {"a","b"}, 2 => {"c"}] 


‘| __ 
JRA 


Multimaps 提 供 了 传统 的 包装 方法 ， 以 及 让 你 选择 Map 和 Collection 类 型 以 自 定义 
Multimap 实 现 的 工具 方法 。 








N 
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Multimap ListMultimap SetMultimap SortedSetMultime 


Wi 


Multimap ListMultimap SetMultimap SortedSetMultime 


Mf GT 


Multimap ListMultimap SetMultimap SortedSetMultime 


Sw * All 


自 定 义 Multimap 的 方法 允许 你 指定 Multimap 中 的 特定 实现 。 但 要 注意 的 是 : 


e Multimap 假 设 对 Map 和 Supplier 产 生 的 集合 对 象 有 完全 所 有 权 。 这 些 自 定义 对 
象 应 避免 手动 更 新 ， 并 且 在 提供 给 Multimap 时 应 该 是 空 的 ， 此 外 还 不 应 该 使 用 
软 引 用 、 弱 引用 或 虚 引 用 。 

e 无 法 保证 修改 了 Multimap 以 后 ， 底 层 Map 的 内 容 是 什么 样 的 。 

e。 即 使 Map 和 Supplier 产 生 的 集合 都 是 线程 安全 的 ， 它 们 组 成 的 Multimap 也 不 能 
保证 并 发 操作 的 线程 安全 性 。 并 发 读 操作 是 工作 正常 的 ， 但 需要 保证 并 发 读 写 
的 话 ， 请 考虑 用 同步 包装 器 解决 。 

e 只 有 当 Map、Supplier、Supplier 产 生 的 集合 对 象 、 以 及 Multimap 存 放 的 键 值 类 
型 都 是 可 序列 化 的 ，Multimap 才 是 可 序列 化 的 。 

e Multimap.get(key) 返 回 的 集合 对 象 和 Supplier 返 回 的 集合 对 象 并 不 是 同一 类 
型 。 但 如 果 Supplier 返 回 的 是 随机 访问 集合 ， 那 么 Multimap.get(key) 返 回 的 集 
合 也 是 可 随机 访问 的 。 


请 注意 ， 用 来 自 定义 Multimap 的 方法 需要 一 个 Supplier 参 数 ， 以 创建 亲 新 的 集合 。 
下 面 有 个 实现 ListMultimap 的 例子 用 TreeMap 做 映射 ， 而 每 个 键 对 应 的 多 个 值 
用 LinkedList 存 储 。 





ListMultimap<String, Integer> myMultimap = Multimaps.newListMultime 
Maps.<String, Collection>newTreeMap(), 
new Supplier<LinkedList>() { 
public LinkedList get() { 
return Lists.newLinkedList(); 


+); 











Tables 


Tables 类 提供 了 若干 称 手 的 工具 方法 。 


EE Table 


Ht [EMultimaps.newXXXMultimap(Map, Supplier) LSA 
3%, Tables.newCustomTable(Map, Supplier&lt;Map&gt;) 人 允许 你 指定 Table 
用 什么 样 的 map 实 现行 和 列 。 


// 使 用 LinkedHashMaps 蔡 代 HashMaps 

Table<String, Character, Integer> table = Tables.newCustomTable( 
Maps.<String, Map<Character, Integer>>newLinkedHashMap(), 

new Supplier<Map<Character, Integer>> () { 

public Map<Character, Integer> get() { 

return Maps.newLinkedHashMap(); 

} 

}); 


transpose 
transpose(Table&lt;R, C, V&agt;) 方法 允许 你 把 Table<C, R, V> 转 置 成 


Table<R, C, V>。 例 如 ， 如 果 你 在 用 Table 构 建 加 权 有 向 图 ， 这 个 方法 就 可 以 把 有 向 
图 反 转 。 


TRA 


还 有 很 多 你 熟悉 和 喜欢 的 Table 包 装 类 。 然 而 ， 在 大 多 数 情况 下 还 请 使 
用 ImmutableTable 


Google Guava 中 文教 程 
Unmodifiable 


Table 


RowSortedTable 


2.3- 强 大 的 集合 工具 类 : java.util.Collections 中 未 包含 的 集合 工具 
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2.4- 集 合 扩展 工具 类 


原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : 丁 一 


ke AN 
ja) J 


有 时 候 你 需要 实现 自己 的 集合 扩展 。 也 许 你 想 要 在 元 素 被 添加 到 列表 时 增加 特定 的 
行为 ， 或 者 你 想 实现 一 个 lterable， 其 底层 实际 上 是 通 万 数据 库 查 询 的 结果 集 。 
Guava 为 你 ， 也 为 我 们 自己 提供 了 若干 工具 方法 ， 以 便 让 类 似 的 工作 变 得 更 简单 。 
(毕竟 ， 我 们 自己 也 要 用 这 些 工具 扩展 集合 框架 。 ) 


Forwarding 装 饰 器 


针对 所 有 类 型 的 集合 接口 ，Guava 都 提供 了 Forwarding 抽 象 类 以 简化 装饰 者 模式 的 
使 用 。 


Forwarding 抽 象 类 定义 了 一 个 抽象 方法 : delegate()， 你 可 以 覆盖 这 个 方法 来 返回 
被 装饰 对 象 。 所 有 其 他 方法 都 会 直接 委托 给 delegate()。 例 如 说 : 
ForwardingList.get(int) 实 际 上 执行 了 delegate().get(int)。 


通过 创建 ForwardingXXX 的 子 类 并 实现 delegate() 方 法 ， 可 以 选择 性 地 覆盖 子 类 的 
方法 来 增加 装饰 功能 ， od tala takin Rss yeas 因为 所 有 方法 都 默 
认 委 托 给 ”delegate() 返 回 的 对 象 ， 你 可 以 只 覆盖 需要 装饰 的 方法 。 


此 外 ， 很 多 集合 方法 都 对 应 一 个 "标准 方法 [standardxxx] 实现， 可 以 用 来 恢复 被 装 
饰 对 象 的 默认 行为 ， 以 提供 相同 的 优点 。 比 如 在 扩展 AbstractList 或 JDK 中 的 其 他 骨 
&R 类 时 ， 可 以 使 用 类 似 standardAddAll 这 样 的 方法 。 


让 我 们 看 看 这 个 例子 。 假 定 你 想 装 饰 一 个 List， 让 其 记录 所 有 添加 进来 的 元 素 。 当 
然 ， 无 论 元 素 是 用 什么 方法 一 一 add(int, E), add(E), 或 addAll(Collection) 一 一 添加 
进来 的 ， 我 们 都 希望 进行 记录 ， 因 此 我 们 需要 覆盖 所 有 这 些 方法 。 











class AddLoggingList<E> extends ForwardingList<E> { 
final List<E> delegate; // backing list 
@Override protected List<E> delegate() { 
return delegate; 


@Override public void add(int index, E elem) { 
log(index, elem); 
super.add(index, elem); 


@Override public boolean add(E elem) { 
return standardAdd(elem); // 用 add(int，E) 实 现 


@Override public boolean addAll(Collection<? extends E> c) { 
return standardAddAll(c); // 用 add 实 现 
} 


记 住 ， 默 认 情 况 下 ， 所 有 方法 都 直接 转发 到 被 代理 对 象 ， 因 此 覆盖 
ForwardingMap.put 并 不 会 改变 ForwardingMap.putAII 的 行为 。 小 心 覆盖 所 有 需要 改 
变 行为 的 方法 ， 并 且 确 保 装 饰 后 的 集合 满足 接口 契约 。 


通常 来 说 ， 类 似 于 AbstractList 的 抽象 集合 骨架 类 ， 其 大 多 数 方 法 在 Forwarding 装 饰 
器 中 都 有 对 应 的 "标准 方法 "实现 。 

对 提供 特定 视图 的 接口 ，Forwarding 装 饰 器 也 为 这 些 视图 提供 了 相应 的 "标准 方 

法 "实现 。 例 如 ，ForwardingMap 提 供 StandardKeySet、StandardValues 和 
StandardEntrySet 类 ， 它 们 在 可 以 的 情况 下 都 会 把 自己 的 方法 委托 给 被 装饰 的 
Map, #248 委托 的 声明 为 抽象 方法 。 


Peekinglterator 


有 时 候 ， 普 通 的 lterator 接 口 还 不 够 。 


lterators 提 供 一 个 Iterators. -peekingIterator (Iterator) 方法 ， 来 把 lterator 
— 为 PeekingIterator ， 这 是 lterator 的 子 类 ， 它 能 让 你 事先 宕 视 [ peek() ] 到 
一 次 调用 next() 返 回 的 元 素 。 


注意 Iterators. A 作 之 后 调用 
remove() 方 法 


举 个 例子 : 复制 一 个 List， 并 去 除 连续 的 重复 元 素 。 


List<E> result = Lists.newArrayList(); 
PeekingIterator<E> iter = Iterators.peekingIterator(source.iteratol 
while (iter.hasNext()) { 
E current = iter.next(); 
while (iter.hasNext() && iter.peek().equals(current)) { 
// 跳 过 重复 的 元 素 


iter.next(); 


result.add(current); 
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传统 的 实现 方式 需要 记录 上 一 个 元 素 ， 并 在 特定 情况 下 后 退 ， 但 这 很 难处 理 且 容易 
出 错 。 相 较 而 言 ，Peekinglterator 在 理解 和 使 用 上 就 比较 直接 了 。 


Abstractlterator 


实现 你 自己 的 lterator? AbstractIterator 让 生活 更 轻松 。 


用 一 个 例子 来 解释 Abstractlterator 最 简单 。 上 比方 说 ， 我 们 要 包装 一 个 iterator 以 跳 过 


空 值 。 


public static Iterator<String> skipNulls(final Iterator<String> in: 
return new AbstractIterator<String>() { 
protected String computeNext() { 

while (in.hasNext()) { 
String s = in.next(); 
if (s != null) { 

return s; 

} 

} 


return endofData( ); 





你 实现 了 computeNext() 方法 ， 来 计算 下 一 个 值 。 如 果 循 环 结束 了 也 没有 找到 下 
一 个 值 ， 请 返回 endOfData() 表 明 已 经 到 达 人 迭代 的 末尾 。 


注意 : Abstractlterator 继 承 了 Unmodifiablelterator， 所 以 禁止 实现 remove() 方 法 。 
如 果 你 需要 支持 remove() 的 迭代 器 ， 就 不 应 该 继承 Abstractlterator。 


AbstractSequentiallterator 


有 一 些 迭 代 器 用 其 他 方式 表示 会 更 简单 。 AbstractSequentialIterator 就 提供 
了 表示 迭代 的 另 一 种 方式 。 


Iterator<Integer> powersOfTwo = new AbstractSequentialIterator<Inte 
protected Integer computeNext(Integer previous) { 
return (previous == 1 << 30) ? null : previous * 2; 
} 
J; 


«| a 








我 们 在 这 儿 实 现 了 computeNext(T) 方法 ， 它 能 接受 前 一 个 值 作为 参数 。 


注意 ， 你 必须 额外 传人 一 个 初始 值 ， 或 者 传人 null 让 和 迭代 立即 结束 。 因 为 
computeNext(T) 假 定 null 值 意味 着 迭代 的 末尾 一 一 AbstractSequentiallterator 不 能 
来 实现 可 能 返回 null 的 迭代 器 。 





3- 缓 存 


原文 地 址 译文 地 址 译 者 : 许 巧 辉 校对 : 沈 义 扬 
sl 


LoadingCache<Key, Graph> graphs = CacheBuilder .newBuilder ( ) 
.maximumSize(1000 ) 
.expireAfterwrite(10, TimeUnit .MINUTES) 
.removalListener (MY_LISTENER) 
. build( 
new CacheLoader<Key, Graph>() { 
public Graph load(Key key) throws AnyException { 
return createExpensiveGraph(key); 
} 
}); 


适用 性 


缓存 在 很 多 场景 下 都 是 相当 有 用 的 。 例 如 ， 计 算 或 检索 一 个 值 的 代价 很 高 ， 并 且 对 
同样 的 输入 需要 不 止 一 次 获取 值 的 时 候 ， 就 应 当 考 虑 使 用 缓存 。 缓存 在 很 多 场景 下 
都 是 相当 有 用 的 。 例 如 ， 计 算 或 检索 一 个 值 的 代价 很 高 ， 并 且 对 同样 的 输入 需要 不 
止 一 次 获取 值 的 时 候 ， 就 应 当 考虑 使 用 缓存 。 


Guava Cache 与 ConcurrentMap 很 相似 ， 但 也 不 完全 一 样 。 最 基本 的 区 别 是 
ConcurrentMap 会 一 直 保 存 所 有 添加 的 元 素 ， 直 到 显 式 地 移 除 。 相 对 地 ，Guava 
Cache 为 了 限制 内 存 占 用 ， 通 常 都 设 定 为 自动 回收 元 素 。 在 某 些 场景 下 ， 尽 管 
LoadingCache 不 回收 元 素 ， 它 也 是 很 有 用 的 ， 因 为 它 会 自动 加 载 缓 存 。 


通常 来 说 ， Guava Cache 适用 于 : 


。 你 愿意 消耗 一 些 内 存 空 间 来 提升 速度 。 

你 预料 到 某 些 键 会 被 查询 一 次 以 上 。 

缓存 中 存放 的 数据 总 量 不 会 超出 内 存 容量 。 (Guava Cache 是 单个 应 用 运行 时 
的 本 地 缓存 。 它 不 把 数据 存放 到 文件 或 外 部 服务 器 。 如 果 这 不 符合 你 的 需求 ， 


请 党 试 Memcached 这 类 工具 ) 
如 果 你 的 场景 符合 上 述 的 每 一 条 ，Guava Cache 就 适合 你 。 


如 同 范例 代码 展示 的 一 样 ，Cache 实 例 通 过 CacheBuilder 生 成 器 模式 获取 ， 但 是 自 
定义 你 的 缓存 才 是 最 有 趣 的 部 分 。 


注 : 如 果 你 不 需要 Cache 中 的 特性 ， 使 用 ConcurrentHashMap 有 更 好 的 内 存 效率 
但 Cache 的 大 多 数 特性 都 很 难 基 于 旧 有 的 ConcurrentMap 复 制 ， 甚 至 根本 不 可 
能 做 到 。 





加 载 


在 使 用 缓存 前 ， 首 先 问 自 己 一 个 问题 : 有 没有 合理 的 默认 方法 来 加 载 或 计算 与 键 关 
联 的 值 ? 如果 有 的 话 ， 你 应 当 使 用 CacheLoader。 如 果 没 有 ， 或 者 你 想 要 覆盖 默认 
的 加 载运 算 ， 同 时 保留 "获取 缓存 -如 果 没 有 - 则 计算 "[get-if-absent-compute] 的 原子 
语义 ， 你 应 该 在 调用 get 时 传 入 一 个 Callable 实 例 。 缓 存 元 素 也 可 以 通过 Cache.put 
TE 但 自动 加 载 是 首选 的 ， 因 为 它 可 以 更 容易 地 推断 所 有 缓存 内 容 的 一 
MIF, 


CacheLoader 


LoadingCache 是 附带 CacheLoader 构 建 而 成 的 缓存 实现 。 创 建 自己 的 
CacheLoader 通 常 只 需要 简单 地 实现 V load(K key) throws Exception 方 法 。 例 如 ， 
你 可 以 用 下 面 的 代码 构建 LoadingCache : 


LoadingCache<Key, Graph> graphs = CacheBuilder .newBuilder ( ) 
.maximumSize(1000 ) 
.build( 
new CacheLoader<Key, Graph>() { 
public Graph load(Key key) throws AnyException { 
return createExpensiveGraph(key); 
} 


}); 


try { 
return graphs.get(key); 
} catch (ExecutionException e) { 
throw new OtherException(e.getCause()); 


} 


从 LoadingCache 查 询 的 正规 方式 是 使 用 get(K) 方 法 。 这 个 方法 要 么 返回 已 经 缓存 的 
值 ， 要 么 使 用 CacheLoader 向 缓存 原子 地 加 载 新 值 。 由 于 CacheLoader 可 能 抛 出 异 
常 ，LoadingCache.get(K) 也 声明 为 抛 出 ExecutionException 异 常 。 如 果 你 定义 的 
CacheLoader 没 有 声明 任何 检查 型 异常 ， 则 可 以 通过 getUnchecked(K) 查 找 缓存 ; 
但 必须 注意 ， 一 旦 CacheLoader 声 明了 检查 型 异常 ， 就 不 可 以 调用 
getUnchecked(K)。 


LoadingCache<Key, Graph> graphs = CacheBuilder .newBuilder ( ) 
.expireAfterAccess(10, TimeUnit.MINUTES) 
.build( 
new CacheLoader<Key, Graph>() { 
public Graph load(Key key) { // no checked exceptic 
return createExpensiveGraph(key); 
} 
}); 


return graphs.getUnchecked(key); 
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getAll(Iterable<? extends K>) 方 法 用 来 执行 批量 查询 。 默 认 情 况 下 ， 对 每 个 不 在 组 
存 中 的 键 ，getAlI 方 法 会 单独 调用 CacheLoaderload 来 加 载 缓存 项 。 如 果 批 量 的 加 
载 比 多 个 单独 加 载 更 高 效 ， 你 可 以 重 载 CacheLoaderloadAll 来 利用 这 一 点 。 
getAll(lterable) 的 性 能 也 会 相应 提升 。 


注 : CacheLoaderloaqdAl/ 的 实现 可 以 为 没有 明确 请 求 的 键 加 载 缓存 值 。 例 如 ， 为 某 
组 中 的 任意 键 计算 值 时 ， 能 够 获取 该 组 中 的 所 有 键 值 ，/oadAl/ 方 法 就 可 以 实现 为 在 
同一 时 间 获 取 该 组 的 其 他 键 值 。 校 注 : getAll(/terable<? extends K>) 方 法 会 调用 
/oadAj， 但 会 筛选 结果 ， 只 会 返回 请 求 的 键 值 对 。 


Callable 


所 有 类 型 的 Guava Cache， 不 管 有 没有 自动 加 载 功 能 ， 都 支持 get(K, Callable<V>) 
方法 。 这 个 方法 返回 缓存 中 相应 的 值 ， 或 者 用 给 定 的 Callable 运 算 并 把 结果 加 入 到 
缓存 中 。 在 整个 加 载 方法 完成 前 ， 缓 存 项 相关 的 可 观察 状态 都 不 会 更 改 。 这 个 方法 
简便 地 实现 了 模式 "如 果 有 缓存 则 返回 ; 否则 运算 、 缓 存 、 然 后 返回 "。 


Cache<Key, Graph> cache = CacheBuilder .newBuilder () 
.maximumSize (1000 ) 
.build(); // look Ma, no CacheLoader 
try { 
// If the key wasn't in the "easy to compute" group, we need tc 
// do things the hard way. 
cache.get(key, new Callable<Key, Graph>() { 
@Override 
public Value call() throws AnyException { 
return doThingsTheHardway (key); 


} 
jr ye 


} catch (ExecutionException e) { 
throw new OtherException(e.getCause()); 
} 
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EAHA 


使 用 cache.put(key, value) 方 法 可 以 直接 向 缓存 中 插入 值 ， 这 会 直接 覆盖 掉 给 定 键 
之 前 映射 的 值 。 使 用 Cache.asMap() 视 图 提供 的 任何 方法 也 能 修改 缓存 。 但 请 注 
意 ，asMap 视 图 的 任何 方法 都 不 能 保证 缓存 项 被 原子 地 加 载 到 缓存 中 。 进 一 步 说 ， 
asMap 视 图 的 原子 运算 在 Guava Cache 的 原子 加 载 范 团 之 外 ， 所 以 相 比 于 

Cache.asMap().putlfAbsent(K, V)，Cache.get(K, Callable<V>) 应 该 总 是 优先 使 


o 


缓存 回收 


一 个 残酷 的 现实 是 ， 我 们 几乎 一 定 没有 足够 的 内 存 缓 存 所 有 数据 。 你 你 必须 决定 : 
什么 时 候 某 个 缓存 项 就 不 值得 保留 了 ? Guava Cache 提 供 了 三 种 基本 的 缓存 回收 方 
式 : 基于 容量 回收 、 定 时 回收 和 基于 引用 回收 。 


基于 容量 的 回收 (size-based eviction) 


如 果 要 规定 缓存 项 的 数目 不 超过 固定 值 ， 只 需 使 

用 cacheBuilder.maximumSize(long) 。 缓 存 将 党 斌 回收 最 近 没 有 使 用 或 总 体 上 
很 少 使 用 的 缓存 项 。 警告 : 在 缓存 项 的 数目 达到 限定 值 之 前 ， 缓 存 就 可 能 进行 
回收 操作 一 一 通常 来 说 ， 这 种 情况 发 生 在 缓存 项 的 数目 逼近 限定 值 时 。 


另外 ， 不 同 的 缓存 项 有 不 同 的 “权重 ”(weights) 例如 ， 如 果 你 的 缓存 值 ， 占 据 
完全 不 同 的 内 存 空间 ， 你 可 以 使 用 cacheBuilder.weigher(Weigher) 指定 一 个 
KEKA, FF AAA cacheBuilder.maximumWeight(long) 指定 最 大 总 重 。 在 权重 
限定 场景 中 ， 除 了 要 注意 回收 也 是 在 重量 盈 近 限定 值 时 就 进行 了 ， 还 要 知道 重量 是 
在 缓存 创建 时 计算 的 ， 因 此 要 考虑 重量 计算 的 复杂 度 。 








LoadingCache<Key, Graph> graphs = CacheBuilder.newBuilder() 
.maximumWeight (100000 ) 
.weigher(new Weigher<Key, Graph>() { 
public int weigh(Key k, Graph g) { 
return g.vertices().size(); 


}) 
.build( 
new CacheLoader<Key, Graph>() { 
public Graph load(Key key) { // no checked exceptic 
return createExpensiveGraph(key); 
} 


}); 





定时 回收 (Timed Eviction) 


CacheBuilder 提供 两 种 定时 回收 的 方法 : 


e expireAfterAccess(long, TimeUnit) : 缓存 项 在 给 定时 间 内 没有 被 读 / 写 
访问 ， 则 回收 。 请 注意 这 种 缓存 的 回收 顺序 和 基于 大 小 回收 一 样 。 

e expireAfterwrite(long, TimeUnit) : 缓存 项 在 给 定时 间 内 没有 被 写 访问 
(创建 或 覆盖 ) ， 则 回收 。 如 果 认 为 缓存 数据 总 是 在 固定 时 候 后 变 得 陈旧 不 可 
用 ， 这 种 回收 方式 是 可 取 的 。 


如 下 文 所 讨论 ， 定 时 回收 周期 性 地 在 写 操 作 中 执行 ， 偶 尔 在 读 操作 中 执行 。 


测试 定时 回收 


对 定时 回收 进行 测试 时 ， 不 一 定 非得 花费 两 秒 钟 去 测试 两 秒 的 过 期 。 你 可 以 使 
用 Ticker 接口 和 cacheBuilder .ticker(Ticker) 方法 在 缓存 中 自 定义 一 个 时 
间 源 ， 而 不 是 非得 用 系统 时 钟 。 


基于 引用 的 回收 (Reference-based Eviction) 


通过 使 用 弱 引 用 的 键 、 或 弱 引 用 的 值 、 或 软 引 用 的 值 ，Guava Cache 可 以 把 缓存 设 
置 为 允许 垃圾 回收 : 


e CacheBuilder.weakkeys() :使 用 弱 引 用 存储 键 。 当 键 没有 其 它 ( 强 或 软 ) 
引用 时 ， 缓 存 项 可 以 被 垃圾 回收 。 因 为 垃圾 回收 仅 依赖 恒等式 (==) ， 使 用 弱 
引用 键 的 缓存 用 == 而 不 是 equals 比 较 键 。 

e CacheBuilder.weakValues() :使 用 弱 引 用 存储 值 。 当 值 没 有 其 它 ( 强 或 
软 ) 引用 时 ， 缓 存 项 可 以 被 垃圾 回收 。 因 为 垃圾 回收 仅 依 赖 恒等式 (==) ， 使 
用 弱 引 用 值 的 缓存 用 == 而 不 是 equals 比 较 值 。 

e CacheBuilder.softValues() :使 用 软 引 用 存储 值 。 软 引用 只 有 在 响应 内 
存 需要 时 ， 才 按照 全 局 最 近 最 少 使 用 的 顺序 回收 。 考 虑 到 使 用 软 引 用 的 性 能 影 
响 ， 我 们 通常 建议 使 用 更 有 性 能 预测 性 的 缓存 大 小 限定 ( 见 上 文 ， 基 于 容量 回 
收 ) 。 使 用 软 引 用 值 的 缓存 同样 用 == 而 不 是 equals 比 较 值 。 


显 式 清除 


任何 时 候 ， 你 都 可 以 显 式 地 清除 缓存 项 ， 而 不 是 等 到 它 被 回收 : 


e 个 别 清 除 : Cache.invalidate(key) 
。 批量 清除 : cache.invalidateAll(keys) 
。 清除 所 有 缓存 项 : Cache.invalidateAll() 


移 除 监听 器 


通过 CacheBuilder.removalListener(RemovalListener) ， 你 可 以 声明 一 个 监 
听 器 ， 以 便 缓 存 项 被 移 除 时 做 一 些 额外 操作 。 缓 存 项 被 移 除 

at, RemovalListener 会 获取 移 除 通知 RemovalNotification ， 其 中 包含 移 除 
原因 Removalcause 、 键 和 值 。 


请 注意 ，RemovalListener 抛 出 的 任何 异常 都 会 在 记录 到 日 志 后 被 丢弃 
[swallowed]. 


CacheLoader<Key, DatabaseConnection> loader = new CacheLoader<Key, 
public DatabaseConnection load(Key key) throws Exception { 
return openConnection(key); 
} 


jp 


RemovalListener<Key, DatabaseConnection> removalListener = new Rem 
public void onRemoval(RemovalNotification<Key, DatabaseConnect: 
DatabaseConnection conn = removal.getValue(); 
conn.close(); // tear down properly 
} 
J; 


return CacheBuilder.newBuilder() 
.expireAfterWrite(2, TimeUnit .MINUTES) 
.removalListener(removalListener ) 
.build(loader ); 





警告 : 默认 情况 下 ， 监 听 器 方法 是 在 移 除 缓存 时 同步 调用 的 。 因 为 缓存 的 维护 和 请 
求 响应 通常 是 同时 进行 的 ， 代 价 高 昂 的 监听 器 方法 在 同步 模式 下 会 拖 慢 正常 的 缓存 
请 求 。 在 这 种 情况 下 ， 你 可 以 使 

用 RemovalListeners.asynchronous(RemovalListener，Executor) 把 监听 器 
装饰 为 异步 操作 。 


清理 什么 时 候 发 生 ? 


使 用 CacheBuilder 构 建 的 缓存 不 会 "自动 "执行 清理 和 回收 工作 ， 也 不 会 在 某 个 缓存 
项 过 期 后 马上 清理 ， 也 没有 诸如 此 类 的 清理 机 制 。 相 反 ， 它 会 在 写 操作 时 顺带 做 少 
量 的 维护 工作 ， 或 者 偶尔 在 读 操作 时 做 一 一 如 果 写 操作 实在 太 少 的 话 。 


这 样 做 的 原因 在 于 : 如 果 要 自动 地 持续 清理 缓存 ， 就 必须 有 一 个 线程 ， 这 个 线程 会 
和 用 户 操作 竞争 共享 锁 。 此 外 ， 某 些 环境 下 线程 创建 可 能 受 限 制 ， 这 样 
CacheBuilder 就 不 可 用 了 。 


相反 ， 我 们 把 选择 权 交 到 你 手 蜂 。 如 果 你 的 缓存 是 高 吞吐 的 ， 那 就 无 需 担心 缓存 的 
维护 和 清理 等 工作 。 如 果 你 的 缓存 只 会 偶尔 有 写 操 作 ， 而 你 又 不 想 清 理工 作 阻 碍 了 
读 操 作 ， 那 么 可 以 创建 自己 的 维护 线程 ， 以 固定 的 时 间 间隔 调 

用 cache.cleanUp() ə ScheduledExecutorService 可 以 帮助 你 很 好 地 实现 这 
样 的 定时 调度 。 


刷新 


刷新 和 回收 不 太一 祥 。 正 如 LoadingCache.refresh(K) 所 声明 ， 刷 新 表示 为 键 加 载 新 
值 ， 这 个 过 程 可 以 是 异步 的 。 在 刷新 操作 进行 时 ， 缓 存 仍然 可 以 向 其 他 线程 返回 旧 
值 ， 而 不 像 回 收 操作 ， 读 缓存 的 线程 必须 等 待 新 值 加载 完 成 。 





如 果 刷 新 过 程 抛 出 异常 ， 缓 存 将 保留 旧 值 ， 而 异常 会 在 记录 到 日 志 后 被 丢弃 
[swallowed]. 


= &CacheLoader.reload(K, V) 可 以 扩展 刷新 时 的 行为 ， 这 个 方法 允许 开发 者 在 计 
算 新 值 时 使 用 旧 的 值 。 


// 有些 键 不 需要 刷新 ， 并 且 我 们 希望 刷新 是 异步 完成 的 
LoadingCache<Key, Graph> graphs = CacheBuilder .newBuilder ( ) 
.maximumSize(1000 ) 
.refreshAfterWrite(1, TimeUnit .MINUTES) 
. build( 
new CacheLoader<Key, Graph>() { 
public Graph load(Key key) { // no checked exceptic 
return getGraphFromDatabase(key); 
} 


public ListenableFuture<Key, Graph> reload(final Ke 
if (neverNeedsRefresh(key)) { 
return Futures.immediateFuture(prevGraph) ; 
selse{ 
// asynchronous! 
ListenableFutureTask<Key, Graph> task=Liste 
public Graph call() { 
return getGraphFromDatabase(key); 


} 
}); 
executor .execute(task); 
return task; 





CacheBuilder.refreshAfterWrite(long, TimeUnit) 可 以 为 缓存 增加 自动 定时 刷新 功 
能 。 和 expireAfterWrite 相 反 ，refreshAfterWrite 通 过 定时 刷新 可 以 让 缓存 项 保持 可 
用 ， 但 请 注意 : 缓存 项 只 有 在 被 检索 时 才 会 真正 刷新 (如果 CacheLoader.refresh 实 
现 为 异步 ， 那 么 检索 不 会 被 刷新 拖 慢 ) 。 因 此 ， 如 果 你 在 缓存 上 同时 声明 
expireAfterWrite 和 refreshAfterWrite， 缓 存 并 不 会 因为 刷新 盲目 地 定时 重 置 ， 如 果 
I 


其 他 特性 


统计 


CacheBuilder.recordStats() 用 来 开启 Guava Cache 的 统计 功能 。 统 计 打 开 
后 ， Cache.stats() 方法 会 返回 cachestats 对 象 以 提供 如 下 统计 信息 : 


e hitRate() : 缓存 命中 率 ; 
e averageLoadPenalty() : 加 载 新 值 的 平均 时 间 ， 单 位 为 纳 秒 ; 
e evictionCount() : 缓存 项 被 回收 的 总 数 ， 不 包括 显 式 清 除 。 


此 外 ， 还 有 其 他 很 多 统计 信息 。 这 些 统计 信息 对 于 调整 缓存 设置 是 至 关 重 要 的 ， 在 
性 能 要 求 高 的 应 用 中 我 们 建议 密切 关注 这 些 数 据 。 


asMap 视 


asMap 视 图 提供 了 缓存 的 ConcurrentMap 形 式 ， 但 asMap 视 图 与 缓存 的 交互 需要 注 


®© : 


e cache.asMap() 包 含 当前 所 有 加 载 到 缓存 的 项 。 因 此 相应 地 ， 
cache.asMap().keySet() 包 含 当 前 所 有 已 加 载 键 ; 

e asMap().get(key) 实 质 上 等 同 于 cache.getlfPresent(key)， 而 且 不 会 引起 缓存 项 
的 加 载 。 这 和 Map 的 语义 约定 一 致 。 

e。 所 有 读 写 操作 都 会 重 置 相关 缓存 项 的 访问 时 间 ， 包 括 
Cache.asMap().get(Object) 方 法 和 Cache.asMap().put(K, V) 方 法 ， 但 不 包括 
Cache.asMap().containsKey(Object) 方 法 ， 也 不 包括 在 Cache.asMap() 的 集合 
视图 上 的 操作 。 上 比如 ， 通 历 Cache.asMap().entrySet() 不 会 重 置 缓存 项 的 读 取 
时 间 。 


中 断 


缓存 加 载 方法 (如 Cache.get) 不 会 抛 出 InterruptedException。 我 们 也 可 以 让 这 些 
方法 支持 InterruptedException， 但 这 种 支持 注定 是 不 完备 的 ， 并 且 会 增加 所 有 使 用 
者 的 成 本 ， 而 只 有 少数 使 用 者 实际 获 益 。 详 情 请 继续 阅读 。 


Cache.get 请 求 到 未 缓存 的 值 时 会 遇 到 两 种 情况 : 当前 线程 加 载 值 ; 或 等 待 另 一 个 
正在 加 载 值 的 线程 。 这 两 种 情况 下 的 中 断 是 不 一 样 的 。 等 待 另 一 个 正在 加 载 值 的 线 
程 属于 较 简 单 的 情况 : 使 用 可 中 断 的 等 待 就 实现 了 中 断 支 持 ; 但 当前 线程 加 载 值 的 
情况 就 比较 复杂 了 : 因为 加 载 值 的 CacheLoader 是 由 用 户 提 供 的 ， 如 果 它 是 可 中 断 
的 ， 那 我 们 也 可 以 实现 支持 中 断 ， 否 则 我 们 也 无 能 为 力 。 


如 果 用 户 提 供 的 CacheLoader 是 可 中 断 的 ， 为 什么 不 让 Cache.get 也 支持 中 断 ? 从 
某 种 意义 上 说 ， 其 实 是 支持 的 : 如 果 CacheLoader 抛 出 InterruptedException， 
Cache.get 将 立刻 返回 (就 和 其 他 异常 情况 一 样 ) ; 此 外 ， 在 加 载 缓存 值 的 线程 
中 ，Cache.get 捕 捉 到 InterruptedException 后 将 恢复 中 断 ， 而 其 他 线程 中 
InterruptedException 则 被 包装 成 了 ExecutionException。 


原则 上 ， 我 们 可 以 拆除 包装 ， 把 ExecutionException 变 为 InterruptedException， 但 
这 会 让 所 有 的 LoadingCache 使 用 者 都 要 处理 中 断 异 常 ， 即 使 他 们 提供 的 
CacheLoader 不 是 可 中 断 的 。 如 果 你 考虑 到 所 有 非 加 载 线程 的 等 待 仍 可 以 被 中 断 ， 
这 种 做 法 也 许 是 值得 的 。 但 许多 缓存 只 在 单线 程 中 使 用 ， 它 们 的 用 户 仍然 必须 捕捉 
不 可 能 抛 出 的 InterruptedException 异 常 。 即 使 是 那些 跨 线 程 共享 缓存 的 用 户 ， 也 只 
是 有 时 候 能 中 断 他 们 的 get 调 用 ， 取 决 于 那个 线程 先 发 出 请 求 。 


对 于 这 个 决定 ， 我 们 的 指导 原则 是 让 缓存 始终 表现 得 好 像 是 在 当前 线程 加 载 值 。 这 
个 原则 让 使 用 缓存 或 每 次 都 计算 值 可 以 简单 地 相互 切换 。 如 果 老 代 码 〈 加 载 值 的 代 
码 ) 是 不 可 中 断 的 ， 那 么 新 代码 〈 使 用 缓存 加 载 值 的 代码 ) 多 半 也 应 该 是 不 可 中 断 
的 。 


如 上 所 述 ，Guava Cache 在 某 种 意义 上 支持 中 断 。 另 一 个 意义 上 说 ，Guava Cache 
不 支持 中 断 ， 这 使 得 LoadingCache 成 了 一 个 有 漏洞 的 抽象 : 当 加 载 过 程 被 中 断 

了 ， 就 当 作 其 他 异常 一 样 处 理 ， 这 在 大 多 数 情况 下 是 可 以 的 ; 但 如 果 多 个 线程 在 等 
待 加载 同 一 个 缓存 项 ， 即 使 加 载 线程 被 中 断 了 ， 它 也 不 应 该 让 其 他 线程 都 失败 ( 捕 
获 到 包装 在 ExecutionException 里 的 InterruptedException) ， 正 确 的 行为 是 让 剩余 
的 某 个 线程 重 斌 加载。 为 此 ， 我 们 记录 了 一 个 bug。 然 而 ， 与 其 冒 着 风险 修复 这 个 
bug， 我 们 可 能 会 花 更 多 的 精力 去 实现 另 一 个 建议 AsyncLoadingCache， 这 个 实现 
会 返回 一 个 有 正确 中 断 行 为 的 Future 对 象 。 
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原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : 丁 一 


SN > 

注意 事项 

截至 JDK7，Java 中 也 只 能 通过 笨拙 元 长 的 匿名 类 来 达到 近似 函数 式 编程 的 效果 。 
预计 JDK8 中 会 有 所 改变 ， 但 Guava 现 在 就 想 给 JDK5 以 上 用 户 提供 这 类 支持 。 


过 度 使 用 Guava 男 数 式 编程 会 导致 元 长 、 混 乱 、 可 读 性 差 而 且 低 效 的 代码 。 这 是 迄 
今 为 止 最 容易 (也 是 最 经 常 ) 被 滥用 的 部 分 ， 如 果 你 想 通 过 函数 式 风格 达成 一 行 代 
码 ， 致 使 这 行 代码 长 到 荒唐 ，Guava 团 队 会 泪 流 满面 。 


比较 如 下 代码 : 
Function<String, Integer> lengthFunction = new Function<String, Ini 


public Integer apply(String string) { 
return string.length(); 
} 
}; 


Predicate<String> allCaps = new Predicate<String>() { 
public boolean apply(String string) { 
return CharMatcher . JAVA_UPPER_CASE.matchesAl1lOf (string); 
} 
}; 


Multiset<Integer> lengths = HashMultiset.create( 
Iterables.transform(Iterables.filter(strings, allCaps), lengtt 


ss 
或 Fluentlterable 的 版 本 





Multiset<Integer> lengths = HashMultiset.create( 
FluentIterable.from(strings) 
.filter(new Predicate<String>() { 
public boolean apply(String string) { 
return CharMatcher . JAVA_UPPER_CASE.matchesA1lOf(st1 


1) 


.transform(new Function<String, Integer>() { 
public Integer apply(String string) { 
return string.length(); 


} 
})); 








还 有 


Multiset<Integer> lengths = HashMultiset.create(); 
for (String string = strings) { 
if (CharMatcher.JAVA_UPPER_CASE.matchesAllOf(string)) { 
lengths.add(string.length()); 


即使 用 了 静态 导入 ， 甚 至 把 Function 和 Predicate 的 声明 放 到 别 的 文件 ， 第 一 种 代码 
实现 仍然 不 简洁 ， 可 读 性 差 并 且 效 率 较 低 。 


截至 JDK7， 命 合式 代码 仍 应 是 默认 和 第 一 选择 。 不 应 该 随便 使 用 沙 数 式 风 格 ， 除 
非 你 绝对 确定 以 下 两 点 之 一 : 


。 使 用 画 数 式 风格 以 后 ， 整 个 工程 的 代码 行 会 净 减 少 。 在 上 面 的 例子 中 ， 事 数 式 
版 本 用 了 11 行 ， 命令 式 代 码 用 了 6 行 ， 把 本 数 的 定义 放 到 另 一 个 文件 或 常量 
中 ， 并 不 能 帮助 减少 总 代码 行 。 

e。 为 了 提高 效率 ， 转 换 集合 的 结果 需要 懒 视图 ， 而 不 是 明确 计算 过 的 集合 。 此 
外 ， 确 保 你 已 经 阅读 和 重读 了 Effective Java 的 第 55 条 ， 并 且 除 了 阅读 本 章 后 面 
的 说 明 ， 你 还 真正 做 了 性 能 测试 并 且 有 测试 数据 来 证 明 画 数 式 版 本 更 快 。 


请 务必 确保 ， 当 使 用 Guava 沙 数 式 的 时 人 息 ， 用 传统 的 命 合式 做 同样 的 事情 不 会 更 具 
可 读 性 。 党 试 把 代码 写 下 来 ， 看 看 它 是 不 是 真 的 那么 糟糕 ? 会 不 会 比 你 想 尝 试 的 极 
其 浴 拙 的 画 数 式 更 具 可 读 性 。 


Functions[2%]4#0Predicates[#T E] 


本 节 只 讨论 直接 与 Function 和 Predicate 打 交道 的 Guava 功 能 。 一 些 其 他 工具 类 也 
FHA AB AK, HIM Iterables.concat(Iterable&lt;Iterable&gt;) , 
和 其 他 用 常量 时 间 返 回 视 图 的 方法 。 党 试看 看 2.3 节 的 集合 工具 类 。 


Guava 提 供 两 个 基本 的 函数 式 接口 : 


e Function<A, B>， 它 声明 了 单个 方法 B apply(Ainput)。Function 对 象 通常 被 预 
期 为 引用 透明 的 一 没有 副作用 一 一 并 且 引 用 透明 性 中 的 "相等 "语义 与 equals 
一 致 ， 如 a.equals(b) 意 味 着 function.apply(a).equals(function.apply(b))。 

e Predicate<T>， 它 声明 了 单个 方法 boolean apply(T input)。Predicate 对 象 通常 
也 被 预期 为 无 副作用 函数 ， 并 且 ” 相 等 ”语义 与 equals 一 致 。 


特殊 的 断言 


字符 类 型 有 自己 特定 版 本 的 Predicate CharMatcher ， 它 通常 更 高 效 ， 并 且 在 
某 些 需求 方面 更 有 用 。CharMatcher 实 现 了 Predicate<Character>， 可 以 当 作 
Predicate 一 样 使 用 ， 要 把 Predicate 转 成 CharMatcher， 可 以 使 

用 CharMatcher.forPredicate 。 更 多 细节 请 参考 第 6 章 - 字 符 串 处 理 。 











此 外 ， 对 可 比较 类 型 和 基于 比较 逻辑 的 Predicate，Range 类 可 以 满足 大 多 数 需求 
一 一 它 表 示 一 个 不 可 变 区 间 。Range 类 实现 了 Predicate， 用 以 判断 值 是 否 在 区 间 
内 。 例 如 ，Range.atMost(2) 就 是 个 完全 合法 的 Predicate<lnteger>。 更 多 使 用 
Range 的 细节 请 参照 第 8 章 。 


操作 Functions 和 Predicates 

Functions 提 供 简便 的 Function 构 造 和 操作 方法 ， 包 括 : 
forMap(Map&lt;A, B&gt; ) compose(Function&lt;B, C&gt;, Function 
identity() toStringFunction() 

细节 请 参考 Javadoc。 


相应 地 ，Predicates 提 供 了 更 多 构造 和 义理 Predicate 的 方法 ， 下 面 是 一 些 例子 : 


instanceOf (Class) assignableFrom(Class) contains(Pattern) 
in(Collection) isNull() alwaysFalse( ) 
alwaysTrue() equalTo(Object ) compose(Predicate, 
and(Predicate. ..) or(Predicate...) not(Predicate) 


细节 请 参考 Javadoc。 


使 用 函数 式 编 程 


Guava 提 供 了 很 多 工具 方法 ， 以 便 用 Function 或 Predicate 操 作 和 集合。 这 些 方 法 通常 
可 以 在 集合 工具 类 找到 ， 如 lterables，Lists，Sets，Maps，Multimaps 等 。 


断言 


断言 的 最 基本 应 用 就 是 过 滤 集 合 。 所 有 Guava 过 滤 方 法 都 返回 "视图 ” 
即 并 非 用 一 个 新 的 集合 表示 过 滤 ， 而 只 是 基于 原 集合 的 视图 。 


译 者 注 : 





集合 类 型 
lterable 
lterator 
Collection 
Set 
SortedSet 
Map 
SortedMap 
Multimap 





过 滤 方 法 

Iterables.filter(Iterable, Predicate) FluentIterable. 
Iterators.filter(Iterator, Predicate) 
Collections2.filter(Collection, Predicate) 
Sets.filter(Set, Predicate) 

Sets.filter(SortedSet, Predicate) 

Maps.filterKeys(Map, Predicate) Maps.filterValues(Map 
Maps.filterKeys(SortedMap, Predicate) Maps.filterValu 


Multimaps.filterKeys(Multimap, Predicate) Multimaps.f 


*List 的 过 滤 视图 被 省 略 了 ， 因 为 不 能 有 效 地 支持 类 似 get(kint) 的 操作 。 请 改 用 
Lists.newArrayList(Collections2.filter(list, predicate)) 做 拷贝 过 滤 。 


除了 简单 过 滤 ，Guava 另 外 提供 了 若干 用 Predicate 义 理 lterable 的 工具 一 一 通常 
在 Iterables 工具 类 中 ， 或 者 是 FluentIterable 的 ”fluent”( 链 式 调用 ) A 


法 。 
lterables** 方 法 签名 ** 说 明 
是 否 所 有 元 素 满足 医 
boolean all(Iterable, Predicate) 懒 实现 : DRA ME 
不 满足 ， 不 会 继续 关 
是 否 有 任意 元 素 满 
boolean any(Iterable, Predicate) 满足 断言 ? 懒 实现 : 
迭代 到 发 现 满足 的 了 
循环 并 返回 一 个 满 
T find(Iterable, Predicate) 满足 断言 的 元 素 ， 妇 


An HLH 


NoSuchElementEx' 
返回 一 个 满足 元 素 ; 


Optional&lt;T&gt; tryFind(Iterable, Predicate) ZWA, ARAN 


E] 0 ptional.absen 
返回 第 一 个 满足 元 录 


indexOf(Iterable, Predicate) 断言 的 元 素 索 引 值 ， 


有 返回 -1 
BIRIA RETR] 


removeIf(Iterable, Predicate) ZTR, £A 





lterator.remove()77: 


BREN 


到 目前 为 止 ， 图 数 最 常见 的 用 途 为 转换 集合 。 同 样 ， 所 有 的 Guava 转 换 方法 也 返回 
原 集合 的 视图 。 


集合 类 型 转换 * 方 法 ** 

lterable Iterables.transform(Iterable, Function) FluentItera 
Iterator Iterators.transform(Iterator, Function) 

Collection Collections2.transform(Collection, Function) 

List Lists  thansrTonm( List, Funct 20m) 

Map* Maps.transformValues(Map, Function) Maps.transformE 
SortedMap* Maps.transformValues(SortedMap, Function) Maps.tran 
Multimap* Multimaps.transformValues(Multimap, Function) Multi 


ListMultimap* Multimaps.transformValues(ListMultimap, Function) M 


Table Tables.transformValues(Table, Function) 


*Map 和 Multimap 有 特殊 的 方法 ， 其 中 有 
个 EntryTransformer&lt;K，V1，V2&gt; 参数 ， 它 可 以 使 用 旧 的 键 值 来 计算 ， 
并 且 用 计算 结果 蔡 换 旧 值 。 


* 对 Set 的 转换 操作 被 省 略 了 ， 因 为 不 能 有 效 支持 contains(Objecb) 操 作 一 一 译 者 注 : 
懒 视图 实际 上 不 会 全 部 计算 转换 后 的 Set 元 素 ， 因 此 不 能 高 效 地 支 

持 contains(Object)。 请 改 用 Sets.newHashSet(Collections2.transform(set, 
function)) 进 行 拷贝 转换 。 


List<String> names; 
Map<String, Person> personWithName; 
List<Person> people = Lists.transform(names, Functions. forMap(pers¢ 


ListMultimap<String, String> firstNameToLastNames; 
// maps first names to all last names of people with that first nar 


ListMultimap<String, String> firstNameToName = Multimaps. transform 
new EntryTransformer<String, String, String> () { 
public String transformEntry(String firstName, String lastl 
return firstName + " " + lastName; 





可 以 组 合 Function 使 用 的 类 包括 : 


Google Guava 中 文教 程 


Ordering 
Predicate 
Equivalence 
Supplier 


Function 


Ordering. onResultOf (Function) 
Predicates.compose(Predicate, Function) 
Equivalence. onResultOf (Function) 
Suppliers.compose(Function, Supplier) 


Functions.compose(Function, Function) 


kA, ListenableFuture API 支 持 转 换 ListenableFuture。Futures 也 提供 了 接 
受 AsyncFunction 参数 的 方法 。AsyncFunction 是 Function 的 变种 ， 它 允许 异步 计 


算 值 。 


Futures.transform(ListenableFuture, Function) 


Futures.transform(ListenableFuture, Function, Executor) 


Futures.transform(ListenableFuture, AsyncFunction) 


Futures.transform(ListenableFuture, AsyncFunction, Executor) 
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5- 并 发 


5.1-google Guava 包 的 ListenableFuture 解 析 


原文 地 址 译 者 : 罗 立 树 校对 : 方 腾飞 


并 发 编程 是 一 个 难题 ， 但 是 一 个 强大 而 简单 的 抽象 可 以 显著 的 简化 并 发 的 编 守 。 出 
于 这 样 的 考虑 ，Guava 定义 了 ListenableFuture 接 口 并 继承 了 JDK concurrent 包 下 
的 Future 接口 。 


我 们 强烈 地 建议 你 在 代码 中 多 使 用 ListenabLleFuture 来 代替 JDK 的 Future , Al 
A: 


e 大 多 数 Futures 方法 中 需要 它 。 

e Fl] ListenableFuture 编程 比较 容易 。 

e Guava 提 供 的 通用 公共 类 封装 了 公共 的 操作 方 方 法 ， 不 需要 提供 Future 
和 ListenableFuture 的 扩展 方法 。 


接口 


传统 JDK 中 的 Future 通 过 异步 的 方式 计算 返回 结果 :在 多 线程 运算 中 可 能 或 者 可 能 在 
没有 结束 返回 结果 ，Future 是 运行 中 的 多 线程 的 一 个 引用 句柄 ， 确 保 在 服务 执行 返 
回 一 个 Result。 


ListenableFuture 可 以 允许 你 注册 回调 方法 (callbacks)， 在 运算 (多 线程 执行 ) 完成 
的 时 候 进 行 调用 , 或 者 在 运算 (多 线程 执行 ) 完成 后 立即 执行 。 这 样 简单 的 改进 ， 
使 得 可 以 明显 的 支持 更 多 的 操作 ， 这 样 的 功能 在 JDK concurrent 中 的 Future 是 不 支 
持 的 。 


ListenableFuture 中 的 基础 方法 是 addListener(Runnable，Executor) ,该 
方法 会 在 多 线程 运算 完 的 时 候 ， 指 定 的 Runnable 参 数 传 人 的 对 象 会 被 指定 的 
Executor 执 行 。 


添加 回调 (Callbacks) 


多 数 用 户 喜 欢 使 用 Futures.addCallback(ListenableFuture<V>, 
FutureCallback<V>, Executor) 的 方式 , 或 者 另外 一 个 版 本 version ( 译 者 

注 : addCallback(ListenableFuture<V> future,FutureCallback<? super V> 
callback)) ， 默 认 是 采用 MoreExecutors.sameThreadExecutor( ) 线 程 池 ,为 了 
简化 使 用 ，Callback 采 用 轻 量 级 的 设计 .Futurecallback&1t;V&gt; 中 实现 了 两 
个 方法 : 


e onSuccess(V) ,在 Future 成 功 的 时 候 执 行 ， 根 据 Future 结 果 来 判断 。 
e onFailure(Throwable) , 在 Future 失 败 的 时 候 执行 ， 根 据 Future 结 果 来 判 
To 


ListenableFuture 的 创建 


对 应 JDK 中 的 ExecutorService.submit(Callable) 提交 多 线程 异步 运算 的 方 
xt, Guava 提供 了 ListeningExecutorService 接口 , 该 接口 返回 
ListenableFuture 而 相应 的 ExecutorService 返回 普通 的 Future 。 将 
ExecutorService 转 为 ListeningExecutorService， 可 以 使 


用 MoreExecutors.listeningDecorator(ExecutorService) 进 行 装饰 。 


ListeningExecutorService service = MoreExecutors.listeningDecorato) 
ListenableFuture explosion = service.submit(new Callable() { 
public Explosion call() { 
return pushBigRedButton(); 
} 
}); 
Futures.addCallback(explosion, new FutureCallback() { 
// we want this handler to run immediately after we push the big 
public void onSuccess(Explosion explosion) { 
walkAwayFrom(explosion); 


public void onFailure(Throwable thrown) { 
battleArchNemesis(); // escaped the explosion! 





另外 , 假如 你 是 从 FutureTask 转 换 而 来 的 , Guava 提 

供 ListenableFutureTask.create(Callable&lt;V&gt; ) 

和 ListenableFutureTask.create(Runnable, V) . 和 JDK 不 同 的 是 ， 
ListenableFutureTask 不 能 随意 被 继承 〈 译 者 注 : ListenableFutureTask 中 的 

done 方 法 实现 了 调用 listener 的 操作 ) 。 


假如 你 喜欢 抽象 的 方式 来 设置 future 的 值 ， 而 不 是 想 实 现 接口 中 的 方法 ， 可 以 考虑 
继承 抽象 类 AbstractFuture&lt;V&gt; 或 者 直接 使 用 SettableFuture o 


假如 你 必须 将 其 他 API 提 供 的 Future 转 换 成 ListenableFuture ， 你 没有 别 的 方法 
只 能 采用 硬 编码 的 方式 JdkFutureAdapters.listenInPoolThread(Future) 来 

将 Future 转换 成 ListenableFuture 。 尽 可 能 地 采用 修改 原生 的 代码 返回 
ListenableFuture 会 更 好 一 些 。 


Application 


使 用 ListenableFuture 最 重要 的 理由 是 它 可 以 进行 一 系列 的 复杂 链 式 的 异步 操 
作 。 


ListenableFuture rowKeyFuture = indexService.lookUp(query); 
AsyncFunction<Rowkey, QueryResult> queryFunction = 

new AsyncFunction<RowKey, QueryResult>() { 

public ListenableFuture apply(RowKey rowKey) { 

return dataService.read(rowKey); 


} 

J; 

ListenableFuture queryFuture = Futures.transform(rowKeyFuture, que) 
‘| _ E- 








其 他 更 多 的 操作 可 以 更 加 有 效 的 支持 而 JDK 中 的 Future 是 没 法 支持 的 . 


不 同 的 操作 可 以 在 不 同 的 Executors 中 执行 ， 单 独 的 ListenableFuture 可 以 有 多 
个 操作 等 待 。 


当 一 个 操作 开始 的 时 候 其 他 的 一 些 操作 也 会 尽快 开始 执行 一 fan- 
out’— ListenableFuture 能 够 满足 这 样 的 场景 : 促 发 所 有 的 回调 (callbacks) 。 
反之 更 简单 的 工作 是 ， 同 样 可 以 满足 "fan-in" 场 景 ， 促 发 ListenableFuture 获取 
(get) 计算 结果 ， 同 时 其 它 的 Futures 也 会 尽快 执行 : 可 以 参考 the 
implementation of Futures.allAsList > ( 译 者 注 : fan-in 和 fan-out 是 软件 设计 
的 一 个 术语 ， 可 以 参考 这 里 http://baike.baidu.com/view/388892.htm#1 或 者 看 这 
里 的 解析 Design Principles: Fan-In vs Fan-Out ， 这 里 fan-out 的 实现 就 是 封装 的 
ListenableFuture 通 过 回调 ， 调 用 其 它 代码 片段 。fan-in 的 意义 是 可 以 调用 其 它 
Future) 


方法 


transform(ListenableFuture&lt;A&gt;, ASyncFunction&lt;A, B&gt;, Ex 


transform(ListenableFuture&lt;A&gt;, Function&lt;A, B&gt;, Executo 


allAsList(Iterable&lt;ListenableFuture&l1t;V&gt;&gt; ) 


successfulAsList(Iterable&lt; ListenableFuture&lt;V&gt;&gt; ) 


AsyncFunction&lt;A, Bagt; 中 提供 一 个 方 
法 ListenableFuture&lt;B&gt; apply(A input), 它 可 以 被 用 于 异步 变换 值 。 


List<ListenableFuture> queries; 
// The queries go to all different data centers, but we want to wa: 


ListenableFuture<List> successfulQueries = Futures.successfulAsList1 


Futures.addCallback(successfulQueries, callbackOnSuccessfulQueries | 


| __& 





CheckedFuture 


Guava 也 提供 了 CheckedFuture&lt;V, X extends Exceptionagt; 接 

口 。 CheckedFuture 是 一 个 ListenableFuture ， 其 中 包含 了 多 个 版 本 的 get 

方法 ， 方 法 声明 抛 出 检查 异常 .这 样 使 得 创建 一 个 在 执行 逮 辑 中 可 以 抛 出 异常 的 
Future 更 加 容易 。 将 ListenableFuture 转换 成 CheckedFuture ， 可 以 使 用 
Futures.makeChecked(ListenableFuture&lt;V&gt;, Functionglt;Exceptiol 
o Guava 也 提供 了 CheckedFuture&lt;V, X extends Exception&gt; 接 


口 。 CheckedFuture 是 一 个 ListenableFuture ， 其 中 包含 了 多 个 版 本 的 get 
ik, SAEIA ERE IR OLB — MERDE AFT LS 常 的 
Future 更 加 容易 。 将 ListenableFuture 转换 成 CheckedFuture ， 可 以 使 用 
Futures.makeChecked(ListenableFuture&lt;V&gt;, Functionglt;Exceptiol 


。 Guava 也 提供 了 CheckedFuture&lt;v, X extends Exception&gt; 接 

口 。 CheckedFuture 是 一 个 ListenableFuture ， 其 中 包含 了 多 个 版 本 的 get 
方法 ， 方法 声明 抛 出 检查 异常 .这 样 使 得 创建 一 个 在 执行 逻辑 中 可 以 抛 出 蛋 常 的 
Future 更 加 容易 。 将 ListenableFuture 转换 成 CheckedFuture ， 可 以 使 用 
Futures.makeChecked(ListenableFuture&lt;V&gt;, Function&lt;Exceptiol 


。 Guava 也 提供 了 checkedFuture&lt;V，X extends Exception&gt; 接 

口 。 CheckedFuture 是 一 个 ListenableFuture ， 其 中 包含 了 多 个 版 本 的 get 
方法 ， 方 法 声明 抛 出 检查 异常 .这 样 使 得 创建 一 个 在 执行 逻辑 中 可 以 抛 出 异常 的 
Future 更 加 容易 。 将 ListenableFuture 转换 成 CheckedFuture ， 可 以 使 用 
Futures.makeChecked(ListenableFuture&lt;V&gt;, Functionglt;Exceptiol 


o Guava 也 提供 了 CheckedFuturealt;V, X extends Exception&gt; 接 

O. CheckedFuture 是 一 个 ListenableFuture ， 其 中 包含 了 多 个 版 本 的 get 
方法 ， 方 法 声明 抛 出 检查 异常 .这 样 使 得 创建 一 个 在 执行 逻辑 中 可 以 抛 出 异常 的 
Future 更 加 容易 。 将 ListenableFuture 转换 成 CheckedFuture ， 可 以 使 用 
Futures.makeChecked(ListenableFuture&lt;V&gt;, Function&lt;Exceptiol 


o Guava 也 提供 了 CheckedFuturealt;V, X extends Exceptionagt; 接 

FH, CheckedFuture 是 一 个 ListenableFuture ， 其 中 包含 了 多 个 版 本 的 get 
方法 ， 方 法 声明 抛 出 检查 异常 .这 样 使 得 创建 一 个 在 执行 逮 辑 中 可 以 抛 出 异常 的 
Future 更 加 容易 # ListenableFuture 转换 成 CheckedFuture ， 可 以 使 用 
Futures.makeChecked(ListenableFuture&lt;V&gt;, Function&lt;Exceptior 


o Guava 也 提供 了 CheckedFuturealt;V, X extends Exception&gt; 接 

O. CheckedFuture 是 一 个 ListenableFuture ， 其 中 包含 了 多 个 版 本 的 get 
方法 ， 方 法 声明 抛 出 检查 异常 .这 样 使 得 创建 一 个 在 执行 逻辑 中 可 以 抛 出 异常 的 
Future 更 加 容易 。 将 ListenableFuture 转换 成 CheckedFuture ， 可 以 使 用 
Futures.makeChecked(ListenableFuture&lt;V&gt;, Function&lt;Exceptiol 


o 


5.2-Google-Guava Concurrent 包 里 的 Service 框 
AR NT 

原文 地 址 译文 地 址 译 者 : 何 一 昕 校对 : 方 腾飞 

概述 


Guava 包 里 的 Service 接 口 用 于 封装 一 个 服务 对 象 的 运行 状态 、 包 括 start 和 stop 等 方 
法 。 例 如 web 服 务 器 ，RPC 服 务 器 、 计 时 器 等 可 以 实现 这 个 接口 。 对 此 类 服务 的 状 
态 管理 并 不 轻松 、 需 要 对 服务 的 开局 /关闭 进行 妥善 管理 、 特 别 是 在 多 线程 环境 下 尤 
为 复杂 。Guava 包 提供 了 一 些 基础 类 帮助 你 管理 复杂 的 状态 转换 逻辑 和 同步 细节 。 


使 用 一 个 服务 
一 个 服务 正常 生命 周期 有 : 


e Service.State. NEW 

e Service.State. STARTING 

e Service.State. RUNNING 

e Service.State. STOPPING 

e Service.State. TERMINATED 


服务 一 且 被 停止 就 无 法 再 重新 启动 了 。 如 果 服 务 在 starting、running、stopping 状 态 
出 现 问题 、 会 进入 Service.State.FAILED .状态 。 调 用 startAsync() 方法 可 

以 异步 开 刻 一 个 服务 ,同时 返回 this 对 象形 成 方法 调用 链 。 注 意 : 只 有 在 当前 服务 的 
状态 是 NEW 时 才能 调用 startAsync() 方 法 ， 因 此 最 好 在 应 用 中 有 一 个 统一 的 地 方 初 
始 化 相关 服务 。 停 止 一 个 服务 也 是 类 似 的 、 使 用 异步 方法 stopAsync() 。 但 是 不 
be ee ee 这 是 为 了 方便 义理 关闭 服务 时 候 的 锁 

竞争 问题 。 


Service 也 提供 了 一 些 方法 用 于 等 待 服务 状态 转换 的 完成 : 


通过 addListener() 方法 异步 添加 监听 器 。 此 方法 允许 你 添加 一 个 
Service.Listener 、 它 会 在 每 次 服务 状态 转换 的 时 候 被 调用 。 注 意 : 最 好 在 服 
务 启动 之 前 添加 Listener (这 时 的 状态 是 NEW) 、 否 则 之 前 已 发 生 的 状态 转换 事件 
是 无 法 在 新 添加 的 Listener 上 被 重新 触发 的 。 


同步 使 用 awaitRunning() 。 这 个 方法 不 能 被 打 断 、 不 强制 捕获 异常 、 一 旦 服务 
启动 就 会 返回 。 如 果 服 务 没 有 成 功 启动 ， 会 抛 出 川 egalStateException 有 异常。 同样 
BY, awaitTerminated() 方法 会 等 待 服务 达到 终止 状态 〈 TERMINATED 或 者 
FAILED ) 。 两 个 方法 都 有 重 载 方 法 允许 传人 超时 时 间 。 


Service 接口 本 身 实现 起 来 会 比较 复 厅 、 且 容易 碰 到 一 些 捉摸 不 透 的 问题 。 因 此 
我 们 不 推荐 直接 实现 这 个 接口 。 而 是 请 继承 Guava 包 里 已 经 封装 好 的 基础 抽象 类 。 
每 个 基础 类 支持 一 种 特定 的 线程 模型 。 


基础 实现 类 


AbstractidleService 


AbstractIdleService 类 简单 实现 了 Service 接 口 、 其 在 running 状 态 时 不 会 执行 
任何 动作 -因此 在 running 时 也 不 需要 和 启动 线程 -但 需要 义理 开启 /关闭 动作 。 要 实现 
一 个 此 类 的 服务 ， 只 需 继承 AbstractldleService 类 ， 然 后 自己 实现 startup() 

和 shutDown() 方法 就 可 以 了 。 


protected void startUp() { 
servlets.add(new GcStatsServlet()); 


protected void shutDown() {} 


如 上 面 的 例子 、 由 于 任何 请 求 到 GcStatsServlet 时 已 经 会 有 现成 线程 处 理 了 ， 所 以 
在 服务 运行 时 就 不 需要 做 什么 额外 动作 了 。 


AbstractExecutionThreadService 


AbstractExecutionThreadService 通过 单线 程 处 理 和 启动、 运行 、 和 关闭 等 操 
作 。 你 必须 重 载 run() 方 法 ， 同 时 需要 能 响应 停止 服务 的 请 求 。 具 体 的 实现 可 以 在 一 
个 循环 内 做 处 理 : 


public void run() { 
while (isRunning()) { 
// perform a unit of work 
} 
} 


另外 ， 你 还 可 以 重 载 triggerShutdown() 方法 让 run() 方 法 结束 返回 。 
重 载 startUp() 和 shutDown() 方 法 是 可 选 的 ， 不 影响 服务 本 身 状态 的 管理 


protected void startUp() { 
dispatcher.listenForConnections(port, queue); 


protected void run() { 
Connection connection; 
while ((connection = queue.take() != POISON)) { 
process(connection); 


} 


protected void triggerShutdown() { 
dispatcher .stopListeningForConnections (queue); 
queue. put(POISON) ; 

} 


start() 内 部 会 调用 startUp() 方 法 ， 创 建 一 个 线程 、 然 后 在 线程 内 调用 run() 方 法 。 
stop() 会 调用 triggerShutdown() 方 法 并 且 等 待 线程 终止 。 


AbstractScheduledService 


AbstractScheduledService 类 用 于 在 运行 时 处 理 一 些 周期 性 的 任务 。 子 类 可 以 
实现 runoneIteration() 方法 定义 一 个 周期 执行 的 任务 ， 以 及 相应 的 startUp() 和 
shutDown() 方 法 。 为 了 能 够 描述 执行 周期 ， 你 需要 实现 scheduler() 方法 。 通 常 
情况 下 ， 你 可 以 使 用 AbstractScheduledService.Scheduler 类 提供 的 两 种 调度 
az: newFixedRateSchedule(initialDelay, delay, TimeUnit) 

和 newFixedDelaySchedule(initialDelay, delay, TimeUnit) ， 类 似 于 JDK 
并 发 包 中 ScheduledExecutorService 类 提供 的 两 种 调度 方式 。 如 要 自 定 义 
schedules 则 可 以 使 用 CcustomScheduler 类 来 辅助 实现 ; 具体 用 法 见 javadoc。 


AbstractService 


如 需要 自 定义 的 线程 管理 、 可 以 通过 扩展 AbstractService 类 来 实现 。 一 般 情 
下 、 使 用 上 面 的 几 个 实现 类 就 已 经 满足 需求 了 ， 但 如 果 在 服务 执行 过 程 中 有 一 Si 
定 的 线程 处 理 需 求 、 则 建议 继承 AbstractService 类 。 


继承 AbstractService 方 法 必须 实现 两 个 方法 . 


e dostart() : 首次 调用 startAsync() 时 会 同时 调用 doStart(),doStart() 内 部 需要 
处 理 所 有 的 初始 化 工作 、 如 果 启 动 成 功 则 调用 notifyStarted() AK; Ba 
失败 则 调用 notifyFailed() 

e dostop() : 首次 调用 stopAsync() 会 同时 调用 doStop(),doStop() 要 做 的 事情 就 
是 停止 服务 ， 如 果 停 止 成 功 则 调用 notifyStopped() 方法 ; 停止 失败 则 调用 
notifyFailed() 方法 。 


doStart 和 doStop 方 法 的 实现 需要 考虑 下 性 能 ， 尽 可 能 的 低 延 迟 。 如 果 初 始 化 的 开销 
较 大 ， 如 读 文件 ， 打 开 网 络 连接 ， 或 者 其 他 任何 可 能 引起 阻塞 的 操作 ， 建 议 移 到 另 
外 一 个 单独 的 线程 去 义理 。 


使 用 ServiceManager 


除了 对 Service 接 口 提 供 基 础 的 实现 类 ，Guava 还 提供 了 ServiceManager 类 使 得 
涉及 到 多 个 Service 集 合 的 操作 更 加 容易 。 通 过 实例 化 ServiceManager 类 来 创建 一 
个 Service 人 集合， 你 可 以 通过 以 下 方法 来 管理 它们 : 


e startAsync() : 将 启动 所 有 被 管理 的 服务 。 如 果 当 前 服务 的 状态 都 是 NEW 
的 话 、 那么 你 只 能 调用 该 方法 一 次 、 这 跟 Service#startAsync() 是 一 样 的 。 

e stopAsync() : 将 停止 所 有 被 管理 的 服务 。 

e addListener : 会 添加 一 一 个 ServiceManager.Listener ， 在 服务 状态 转 
换 中 会 调用 该 Listener 

e awaitHealthy() : 会 等 待 所 有 的 服务 达到 Running 状 态 

e awaitStopped() : 会 等 待 所 有 服务 达到 终止 状态 


仿 测 类 的 方法 有 : 


e isHealthy() **:** 如 果 所 有 的 服务 处 于 Running 状 态 、 会 返回 True 

e servicesByState() : 以 状态 为 索引 返回 当前 所 有 服务 的 快照 

e startupTimes() : 返回 一 个 Map 对 象 ， 记 录 被 管理 的 服务 启动 的 耗 时 、 以 
毫秒 为 单位 ， 同 时 Map 默 认 按 启动 时 间 排 序 。 


lee 个 服务 的 生命 周期 都 能 通过 ServiceManager 来 管理 ， 不 过 oo 
是 通过 其 他 机 制 触发 的 、 也 不 影响 ServiceManager 方 法 的 正确 执行 。 例 如 : 当 一 
服务 不 是 通过 startAsync()、 而 是 其 他 机 制 启 动 时 ，listeners 仍然 可 以 被 正常 调用 、 
awaitHealthy() 也 能 够 正常 工作 。ServiceManager 唯一 强制 的 要 求 是 当 其 被 创建 时 
所 有 的 服务 必须 处 于 New 状 态 。 


Mt : TestCase、 也 可 以 作为 练习 Demo 


ServiceTest 


* Copyright (C) 2013 The Guava Authors 


Licensed under the Apache License, Version 2.0 (the "License"); 
you may not use this file except in compliance with the License 
You may obtain a copy of the License at 


http://www.apache.org/licenses/LICENSE -2.0 


Unless required by applicable law or agreed to in writing, softy 
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package com.google.common.util.concurrent; 


import static com.google.common.util.concurrent.Service.State.FAILt 
import static com.google.common.util.concurrent.Service.State.NEw; 
import static com.google.common.util.concurrent.Service.State.RUNN: 
import static com.google.common.util.concurrent.Service.State.STAR 
import static com.google.common.util.concurrent.Service.State.STOPI 
import static com.google.common.util.concurrent.Service.State. TERM: 


import junit.framework.TestCase; 


Ce 
* Unit tests for {@link Service} 
ey 
public class ServiceTest extends TestCase { 


/** Assert on the comparison ordering of the State enum since we gl 
public void testStateOrdering() { 

// List every valid (direct) state transition. 

assertLessThan(NEW, STARTING); 

assertLessThan(NEW, TERMINATED); 


assertLessThan(STARTING, RUNNING); 
assertLessThan(STARTING, STOPPING); 
assertLessThan(STARTING, FAILED); 


assertLessThan(RUNNING, STOPPING); 
assertLessThan(RUNNING, FAILED); 


assertLessThan(STOPPING, FAILED); 
assertLessThan(STOPPING, TERMINATED); 


} 


private static <T extends Comparable<? super T>> void assertLessTt 
if (a.compareTo(b) >= 0) { 
fail(String.format("Expected %s to be less than %s", a, b)); 
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* Copyright (C) 2009 The Guava Authors 
* 
* Licensed under the Apache License, Version 2.0 (the "License"); 
* you may not use this file except in compliance with the License 
* You may obtain a copy of the License at 
* 
* http://www.apache.org/licenses/LICENSE-2.0 
* 
* Unless required by applicable law or agreed to in writing, softy 
* distributed under the License is distributed on an "AS IS" BASIS 
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
* See the License for the specific language governing permissions 
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limitations under the License. 
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package com.google.common.util.concurrent; 
import static org.truthO0.Truth.ASSERT; 
import com.google.common.collect.Lists; 
import junit.framework.TestCase; 
import java.util.List; 
import java.util.concurrent.Executor; 
import java.util.concurrent.TimeUnit; 
import java.util.concurrent.TimeoutException; 
[irs 

* Tests for {@link AbstractIdleService}. 


* 


* @author Chris Nokleberg 
* @author Ben Yu 
BA 
public class AbstractIdleServiceTest extends TestCase { 


// Functional tests using real thread. We only verify publicly vis: 
// Interaction assertions are done by the single-threaded unit te: 


public static class FunctionalTest extends TestCase { 


private static class DefaultService extends AbstractIdleService { 
@Override protected void startUp() throws Exception {} 
@Override protected void shutDown() throws Exception {} 


} 


public void testServiceStartStop() throws Exception { 
AbstractIdleService service = new DefaultService(); 
service.startAsync().awaitRunning(); 
assertEquals(Service.State.RUNNING, service.state()); 
service.stopAsync().awaitTerminated(); 
assertEquals(Service.State.TERMINATED, service.state()); 
} 


public void testStart_failed() throws Exception { 

final Exception exception = new Exception("deliberate"); 
AbstractIdleService service = new DefaultService() { 
@Override protected void startUp() throws Exception { 
throw exception; 


service.startAsync().awaitRunning(); 

fail(); 

} catch (RuntimeException e) { 

assertSame(exception, e.getCause()); 

} 

assertEquals(Service.State.FAILED, service.state()); 


} 


public void testStop_failed() throws Exception { 

final Exception exception = new Exception("deliberate"); 
AbstractIdleService service = new DefaultService() { 
@Override protected void shutDown() throws Exception { 
throw exception; 

} 

}; 

service.startAsync().awaitRunning(); 

try { 

service.stopAsync().awaitTerminated(); 

fail(); 

} catch (RuntimeException e) { 

assertSame(exception, e.getCause()); 


} 


assertEquals(Service.State.FAILED, service.state()); 


} 
} 


public void testStart() { 

TestService service = new TestService(); 

assertEquals(0, service.startUpCalled); 
service.startAsync().awaitRunning(); 

assertEquals(1, service.startUpCalled); 
assertEquals(Service.State.RUNNING, service.state()); 

ASSERT. that(service.transitionStates).has().exactly(Service.State 


} 


public void testStart_failed() { 

final Exception exception = new Exception("deliberate"); 
TestService service = new TestService() { 

@Override protected void startUp() throws Exception { 
super.startUp(); 

throw exception; 

} 

}; 

assertEquals(0, service.startUpCalled); 

try { 

service.startAsync().awaitRunning(); 

fail(); 

} catch (RuntimeException e) { 

assertSame(exception, e.getCause()); 

} 

assertEquals(1, service.startUpCalled); 
assertEquals(Service.State.FAILED, service.state()); 
ASSERT. that(service.transitionStates).has().exactly(Service.State 


} 


public void testStop_withoutStart() { 

TestService service = new TestService(); 
service.stopAsync().awaitTerminated(); 

assertEquals(0, service.startUpCalled); 

assertEquals(0, service.shutDownCalled) ; 
assertEquals(Service.State. TERMINATED, service.state()); 
ASSERT. that(service.transitionStates).isEmpty(); 


} 


public void testStop_afterStart() { 

TestService service = new TestService(); 
service.startAsync().awaitRunning(); 

assertEquals(1, service.startUpCalled); 

assertEquals(0, service.shutDownCalled) ; 
service.stopAsync().awaitTerminated(); 

assertEquals(1, service.startUpCalled); 

assertEquals(1, service.shutDownCalled) ; 
assertEquals(Service.State. TERMINATED, service.state()); 
ASSERT. that(service.transitionStates) 
.has().exactly(Service.State.STARTING, Service.State.STOPPING) . in( 


} 


public void testStop_failed() { 

final Exception exception = new Exception("deliberate"); 
TestService service = new TestService() { 

@Override protected void shutDown() throws Exception { 
super .shutDown(); 

throw exception; 

} 

}; 

service.startAsync().awaitRunning(); 

assertEquals(1, service.startUpCalled); 
assertEquals(0, service.shutDownCalled) ; 

try { 

service.stopAsync().awaitTerminated(); 

fail(); 

} catch (RuntimeException e) { 

assertSame(exception, e.getCause()); 


assertEquals(1, service.startUpCalled); 

assertEquals(1, service.shutDownCalled) ; 
assertEquals(Service.State.FAILED, service.state()); 

ASSERT. that(service.transitionStates ) 
.has().exactly(Service.State.STARTING, Service.State.STOPPING) . in( 
} 


public void testServiceToString() { 

AbstractIdleService service = new TestService(); 
assertEquals("TestService [NEW]", service.toString()); 
service.startAsync().awaitRunning(); 
assertEquals("TestService [RUNNING]", service.toString()); 
service.stopAsync().awaitTerminated(); 
assertEquals("TestService [TERMINATED]", service.toString()); 
} 


public void testTimeout() throws Exception { 

// Create a service whose executor will never run its commands 
Service service = new TestService() { 

@Override protected Executor executor() { 

return new Executor() { 

@Override public void execute(Runnable command) {} 


try { 

service.startAsync().awaitRunning(1, TimeUnit.MILLISECONDS); 
fail("Expected timeout"); 

} catch (TimeoutException e) { 

ASSERT. that (e.getMessage()).contains(Service.State.STARTING.toStr: 
} 

} 


private static class TestService extends AbstractIdleService { 


int startUpCalled = 0; 
int shutDownCalled = 0; 
final List<State> transitionStates = Lists.newArrayList(); 


@Override protected void startUp() throws Exception { 
assertEquals(0, startUpCalled); 
assertEquals(0, shutDownCalled) ; 
startUpCalled++; 
assertEquals(State.STARTING, state()); 


} 


@Override protected void shutDown() throws Exception { 
assertEquals(1, startUpCalled); 
assertEquals(0, shutDownCalled) ; 
shutDownCalled++; 
assertEquals(State.STOPPING, state()); 


} 


@Override protected Executor executor() { 
transitionStates.add(state()); 
return MoreExecutors.sameThreadExecutor(); 
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Licensed under the Apache License, Version 2.0 (the "License"); 
you may not use this file except in compliance with the License 
You may obtain a copy of the License at 


http: //www.apache.org/licenses/LICENSE -2.0 


Unless required by applicable law or agreed to in writing, softy 
distributed under the License is distributed on an "AS IS" BASIS 
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 
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package com.google.common.util.concurrent; 


import com.google.common.util.concurrent.AbstractScheduledService.: 
import com.google.common.util.concurrent.Service.State; 


import junit.framework.TestCase; 


import java.util.concurrent.CountDownLatch; 

import java.util.concurrent.CyclicBarrier; 

import java.util.concurrent.ExecutionException; 
import java.util.concurrent.Executors; 

import java.util.concurrent.Future; 

import java.util.concurrent.ScheduledExecutorService; 
import java.util.concurrent.ScheduledFuture; 

import java.util.concurrent.ScheduledThreadPoolExecutor ; 
import java.util.concurrent.TimeUnit; 

import java.util.concurrent.atomic.AtomicBoolean; 
import java.util.concurrent.atomic.AtomicInteger; 


ff FRR 
* Unit test for {@link AbstractScheduledService}. 
* 
* @author Luke Sandberg 
Ww 


public class AbstractScheduledServiceTest extends TestCase { 


volatile Scheduler configuration = Scheduler .newFixedDelaySchedule| 
volatile ScheduledFuture<?> future = null; 


volatile boolean atFixedRateCalled = false; 
volatile boolean withFixedDelayCalled = false; 
volatile boolean scheduleCalled = false; 


final ScheduledExecutorService executor = new ScheduledThreadPoolE> 
@Override 

public ScheduledFuture<?> schedulewithFixedDelay(Runnable command, 
long delay, TimeUnit unit) { 

return future = super.schedulewithFixedDelay(command, initialDelay 
} 

}; 


public void testServiceStartStop() throws Exception { 
NullService service = new NullService(); 
service.startAsync().awaitRunning(); 
assertFalse(future.isDone()); 
service.stopAsync().awaitTerminated(); 
assertTrue(future.isCancelled()); 


} 


private class NullService extends AbstractScheduledService { 
@Override protected void runOneIteration() throws Exception {} 
@Override protected Scheduler scheduler() { return configuration; 
@Override protected ScheduledExecutorService executor() { return 4 


} 


public void testFailOnExceptionFromRun() throws Exception { 


TestService service = new TestService(); 
service.runException = new Exception(); 
service.startAsync().awaitRunning(); 
service.runFirstBarrier.await(); 
service.runSecondBarrier.await(); 

try { 

future. get(); 

fail(); 

} catch (ExecutionException e) { 

// An execution exception holds a runtime exception (from throwab- 
// original exception. 

assertEquals(service.runException, e.getCause().getCause()); 


} 


assertEquals(service.state(), Service.State.FAILED); 


} 


public void testFailOnExceptionFromStartUp() { 
TestService service = new TestService(); 
service.startUpException = new Exception(); 

try { 

service.startAsync().awaitRunning(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.startUpException, e.getCause()); 
} 

assertEquals(0, service.numberOfTimesRunCalled.get()); 
assertEquals(Service.State.FAILED, service.state()); 


} 


public void testFailOnExceptionFromShutDown() throws Exception { 
TestService service = new TestService(); 
service.shutDownException = new Exception(); 
service.startAsync().awaitRunning(); 
service.runFirstBarrier.await(); 

service.stopAsync(); 

service. runSecondBarrier.await(); 

try { 

service.awaitTerminated(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.shutDownException, e.getCause()); 


} 


assertEquals(Service.State.FAILED, service.state()); 


} 


public void testRunOneIterationCalledMultipleTimes() throws Except: 
TestService service = new TestService(); 
service.startAsync().awaitRunning(); 

FOR (Gmt Sa a Oe IE) 

service.runFirstBarrier.await(); 

assertEquals(i, service.numberOfTimesRunCalled.get()); 

service. runSecondBarrier.await(); 


} 


service.runFirstBarrier.await(); 
service.stopAsync(); 

service. runSecondBarrier.await(); 
service.stopAsync().awaitTerminated(); 


} 


public void testExecutorOnlyCalledOnce() throws Exception { 
TestService service = new TestService(); 
service.startAsync().awaitRunning(); 

// It should be called once during startup. 

assertEquals(1, service.numberOfTimesExecutorCalled.get()); 
ror (ine i ere PC aa i 
service.runFirstBarrier.await(); 

assertEquals(i, service.numberOfTimesRunCalled.get()); 
service. runSecondBarrier.await(); 

} 

service.runFirstBarrier.await(); 

service.stopAsync(); 

service. runSecondBarrier.await(); 
service.stopAsync().awaitTerminated(); 

// Only called once overall. 

assertEquals(1, service.numberOfTimesExecutorCalled.get()); 


} 


public void testDefaultExecutorIsShutdownwhenServiceIsStopped() thi 
final CountDownLatch terminationLatch = new CountDownLatch(1); 
AbstractScheduledService service = new AbstractScheduledService() 
volatile ScheduledExecutorService executorService; 

@Override protected void runOneIteration() throws Exception {} 


@Override protected ScheduledExecutorService executor() { 
if (executorService == null) { 
executorService = super.executor(); 
// Add a listener that will be executed after the listener that st 
addListener(new Listener() { 
@Override public void terminated(State from) { 
terminationLatch.countDown(); 


} 


}, MoreExecutors.sameThreadExecutor()); 


} 


return executorService; 


} 


@Override protected Scheduler scheduler() { 
return Scheduler .newFixedDelaySchedule(0, 1, TimeUnit .MILLISECONDS‘ 


J}; 


service.startAsync(); 
assertFalse(service.executor().isShutdown()); 
service.awaitRunning(); 
service.stopAsync(); 
terminationLatch.await(); 
assertTrue(service.executor().isShutdown()); 


assertTrue(service.executor().awaitTermination(100, TimeUnit.MILL: 


} 


public void testDefaultExecutorIsShutdownwhenServiceFails() throws 
final CountDownLatch failureLatch = new CountDownLatch(1); 
AbstractScheduledService service = new AbstractScheduledService() 
volatile ScheduledExecutorService executorService; 

@Override protected void runOneIteration() throws Exception {} 


@Override protected void startUp() throws Exception { 
throw new Exception("Failed"); 


} 


@Override protected ScheduledExecutorService executor() { 

if (executorService == null) { 

executorService = super.executor(); 

// Add a listener that will be executed after the listener that st 
addListener(new Listener() { 

@Override public void failed(State from, Throwable failure) { 
failureLatch.countDown(); 

} 

}, MoreExecutors.sameThreadExecutor()); 

} 


return executorService; 


} 


@Override protected Scheduler scheduler() { 
return Scheduler .newFixedDelaySchedule(0, 1, TimeUnit .MILLISECOND<‘ 
thr 


try { 
service.startAsync().awaitRunning(); 


fail("Expected service to fail during startup"); 

} catch (IllegalStateException expected) {} 

failureLatch.await(); 

assertTrue(service.executor().isShutdown()); 
assertTrue(service.executor().awaitTermination(100, TimeUnit.MILL: 


} 


public void testSchedulerOnlyCalledOnce() throws Exception { 
TestService service = new TestService()j; 
service.startAsync().awaitRunning(); 

// It should be called once during startup. 

assertEquals(1, service.numberOfTimesSchedulerCalled.get()); 
On (nt a= el ea =O Le) i 
service.runFirstBarrier.await(); 

assertEquals(i, service.numberOfTimesRunCalled.get()); 
service. runSecondBarrier.await(); 

} 

service.runFirstBarrier.await(); 

service.stopAsync(); 

service. runSecondBarrier.await(); 
service.awaitTerminated(); 


// Only called once overall. 
assertEquals(1, service.numberOfTimesSchedulerCalled.get()); 


} 


private class TestService extends AbstractScheduledService { 
CyclicBarrier runFirstBarrier = new CyclicBarrier(2); 
CyclicBarrier runSecondBarrier = new CyclicBarrier(2); 


volatile boolean startUpCalled = false; 

volatile boolean shutDownCalled = false; 

AtomicInteger numberOfTimesRunCalled = new AtomicInteger(0); 
AtomicInteger numberOfTimesExecutorCalled = new AtomicInteger(0); 
AtomicInteger numberOfTimesSchedulerCalled = new AtomicInteger (0), 
volatile Exception runException = null; 

volatile Exception startUpException = null; 

volatile Exception shutDownException = null; 


@Override 
protected void runOneIteration() throws Exception { 
assertTrue(startUpCalled) ; 
assertFalse(shutDownCalled) ; 
numberOfTimesRunCalled.incrementAndGet(); 
assertEquals(State.RUNNING, state()); 
runFirstBarrier.await(); 
runSecondBarrier.await(); 
if (runException != null) { 
throw runException; 
} 
} 


@Override 
protected void startUp() throws Exception { 
assertFalse(startUpCalled); 
assertFalse(shutDownCalled) ; 
startUpCalled = true; 
assertEquals(State.STARTING, state()); 
if (startUpException != null) { 
throw startUpException; 
} 
} 


@Override 
protected void shutDown() throws Exception { 
assertTrue(startUpCalled) ; 
assertFalse(shutDownCalled) ; 
shutDownCalled = true; 
if (shutDownException != null) { 
throw shutDownException; 
} 
} 


@Override 
protected ScheduledExecutorService executor() { 


numberOfTimesExecutorCalled.incrementAndGet(); 
return executor; 


} 


@Override 
protected Scheduler scheduler() { 
numberOfTimesSchedulerCalled.incrementAndGet(); 
return configuration; 
} 
} 


public static class SchedulerTest extends TestCase { 

// These constants are arbitrary and just used to make sure that 1 
// with the correct parameters. 

private static final int initialDelay = 10; 

private static final int delay = 20; 

private static final TimeUnit unit = TimeUnit.MILLISECONDS; 


// Unique runnable object used for comparison. 
final Runnable testRunnable = new Runnable() {@Override public vo: 
boolean called = false; 


private void assertSingleCallwithCorrectParameters(Runnable comman 
long delay, TimeUnit unit) { 

assertFalse(called); // only called once. 

called = true; 

assertEquals(SchedulerTest.initialDelay, initialDelay); 
assertEquals(SchedulerTest.delay, delay); 
assertEquals(SchedulerTest.unit, unit); 

assertEquals(testRunnable, command); 


} 


public void testFixedRateSchedule() { 
Scheduler schedule = Scheduler .newFixedRateSchedule(initialDelay, 
schedule.schedule(null, new ScheduledThreadPoolExecutor(1) { 
@Override 
public ScheduledFuture<?> scheduleAtFixedRate(Runnable command, 1 
long period, TimeUnit unit) { 
assertSingleCallwithCorrectParameters(command, initialDelay, dela\ 
return null; 
} 
}, testRunnable); 
assertTrue(called); 


} 


public void testFixedDelaySchedule() { 
Scheduler schedule = Scheduler .newFixedDelaySchedule(initialDelay, 
schedule.schedule(null, new ScheduledThreadPoolExecutor(10) { 
@Override 
public ScheduledFuture<?> schedulewithFixedDelay(Runnable command, 
long delay, TimeUnit unit) { 
assertSingleCallwithCorrectParameters(command, initialDelay, delaj 
return null; 


} 
}, testRunnable); 


assertTrue(called); 


} 


private class TestCustomScheduler extends AbstractScheduledService 
public AtomicInteger scheduleCounter = new AtomicInteger(0); 
@Override 
protected Schedule getNextSchedule() throws Exception { 
scheduleCounter.incrementAndGet ( ); 
return new Schedule(0, TimeUnit.SECONDS); 
} 
} 


public void testCustomSchedule_startStop() throws Exception { 
final CyclicBarrier firstBarrier = new CyclicBarrier(2); 
final CyclicBarrier secondBarrier = new CyclicBarrier(2); 
final AtomicBoolean shouldWait = new AtomicBoolean(true); 
Runnable task = new Runnable() { 

@Override public void run() { 

try { 

if (shouldwait.get()) 
firstBarrier.await(); 
secondBarrier.await() 
} 

} catch (Exception e) { 

throw new RuntimeException(e); 

} 

} 

}; 

TestCustomScheduler scheduler = new TestCustomScheduler(); 
Future<?> future = scheduler.schedule(null, Executors.newSchedulec 
firstBarrier.await(); 

assertEquals(1, scheduler.scheduleCounter.get()); 
secondBarrier.await(); 

firstBarrier.await(); 

assertEquals(2, scheduler.scheduleCounter.get()); 
shouldwait.set(false); 

secondBarrier.await(); 

future.cancel( false); 


} 


{ 


了 


public void testCustomSchedulerServiceStop() throws Exception { 
TestAbstractScheduledCustomService service = new TestAbstractSchec 
service.startAsync().awaitRunning(); 

service. firstBarrier.await(); 

assertEquals(1, service.numIterations.get()); 

service.stopAsync(); 

service.secondBarrier.await(); 

service.awaitTerminated(); 

// Sleep for a while just to ensure that our task wasn't called ac 
Thread.sleep(unit.toMillis(3 * delay)); 

assertEquals(1, service.numIterations.get()); 


} 


public void testBig() throws Exception { 
TestAbstractScheduledCustomService service = new TestAbstractSchec 
@Override protected Scheduler scheduler() { 
return new AbstractScheduledService.CustomScheduler() { 
@Override 
protected Schedule getNextSchedule() throws Exception { 
// Explicitly yield to increase the probability of a pathological 
Thread. yield(); 
return new Schedule(0, TimeUnit.SECONDS) ; 
} 
}; 
} 
}; 
service.useBarriers = false; 
service.startAsync().awaitRunning(); 
Thread.sleep(50); 
service.useBarriers = true; 
service.firstBarrier.await(); 
int numIterations = service.numIterations.get(); 
service.stopAsync(); 
service.secondBarrier.await(); 
service.awaitTerminated(); 
assertEquals(numIterations, service.numIterations.get()); 


} 


private static class TestAbstractScheduledCustomService extends Ab: 
final AtomicInteger numIterations = new AtomicInteger(0); 
volatile boolean useBarriers = true; 

final CyclicBarrier firstBarrier = new CyclicBarrier(2); 

final CyclicBarrier secondBarrier = new CyclicBarrier(2); 


@Override protected void runOneIteration() throws Exception { 
numIterations.incrementAndGet(); 
if (useBarriers) { 
firstBarrier.await(); 
secondBarrier.await(); 
} 
} 


@Override protected ScheduledExecutorService executor() { 
// use a bunch of threads so that weird overlapping schedules are 
return Executors.newScheduledThreadPool(10); 


} 


@Override protected void startUp() throws Exception {} 
@Override protected void shutDown() throws Exception {} 
@Override protected Scheduler scheduler() { 


return new CustomScheduler() { 
@Override 


protected Schedule getNextSchedule() throws Exception { 
return new Schedule(delay, unit); 

thr 

} 

} 


public void testCustomSchedulerFailure() throws Exception { 
TestFailingCustomScheduledService service = new TestFailingCustoms 
service.startAsync().awaitRunning(); 

fOr (ni wo = tLe Ae AP ee ie 

service. firstBarrier.await(); 

assertEquals(i, service.numIterations.get()); 
service.secondBarrier.await(); 


} 

Thread.sleep(1000); 

try { 

service.stopAsync().awaitTerminated(100, TimeUnit.SECONDS) ; 
fail(); 

} catch (IllegalStateException e) { 
assertEquals(State.FAILED, service.state()); 

} 

} 


private static class TestFailingCustomScheduledService extends Absi 
final AtomicInteger numIterations = new AtomicInteger(0); 
final CyclicBarrier firstBarrier = new CyclicBarrier(2); 
final CyclicBarrier secondBarrier = new CyclicBarrier(2); 


@Override protected void runOneIteration() throws Exception { 
numIterations.incrementAndGet ( ); 
firstBarrier.await(); 
secondBarrier.await(); 


} 


@Override protected ScheduledExecutorService executor() { 
// use a bunch of threads so that weird overlapping schedules are 
return Executors.newScheduledThreadPool(10); 


} 


@Override protected Scheduler scheduler() { 

return new CustomScheduler() { 

@Override 

protected Schedule getNextSchedule() throws Exception { 
if (numIterations.get() > 2) { 

throw new IllegalStateException("Failed"); 

} 


return new Schedule(delay, unit); 
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package com.google.common.util.concurrent; 


import static java.lang.Thread.currentThread; 
import static java.util.concurrent.TimeUnit .SECONDS; 


import com.google.common.collect.ImmutableList; 

import com.google.common.collect.Iterables; 

import com.google.common.collect.Lists; 

import com.google.common.util.concurrent.Service.Listener; 
import com.google.common.util.concurrent.Service.State; 


import junit.framework.TestCase; 


import java.lang.Thread.UncaughtExceptionHandler; 
import java.util.List; 

import java.util.concurrent.CountDownLatch; 

import java.util.concurrent.TimeUnit; 

import java.util.concurrent.atomic.AtomicInteger; 
import java.util.concurrent.atomic.AtomicReference; 


import javax.annotation.concurrent.GuardedBy; 


Hf sro 
* Unit test for {@link AbstractService}. 
* 
* @author Jesse Wilson 
iar 
public class AbstractServiceTest extends TestCase { 


private Thread executionThread; 
private Throwable thrownByExecutionThread; 


public void testNoOpServiceStartStop() throws Exception { 
NoOpService service = new NoOpService(); 
RecordingListener listener = RecordingListener.record(service); 


assertEquals(State.NEW, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service. running); 


service.startAsync(); 
assertEquals(State.RUNNING, service.state()); 
assertTrue(service.isRunning()); 
assertTrue(service.running) ; 


service.stopAsync(); 
assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service. running); 
assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.STOPPING, 

State. TERMINATED), 
listener.getStateHistory()); 


} 


public void testNoOpServiceStartAndwaitStopAndwait() throws Except: 
NoOpService service = new NoOpService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


} 


public void testNoOpServiceStartAsyncAndAwaitStopAsyncAndAwait() tl 
NoOpService service = new NoOpService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync().awaitTerminated(); 
assertEquals(State.TERMINATED, service.state()); 


} 


public void testNoOpServiceStopIdempotence() throws Exception { 
NoOpService service = new NoOpService(); 

RecordingListener listener = RecordingListener.record(service); 
service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync(); 

service.stopAsync(); 

assertEquals(State. TERMINATED, service.state()); 
assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.STOPPING, 

State. TERMINATED), 

listener.getStateHistory()); 


} 


public void testNoOpServiceStopIdempotenceAfterWait() throws Except 


NoOpService service = new NoOpService(); 
service.startAsync().awaitRunning(); 


service.stopAsync().awaitTerminated(); 
service.stopAsync(); 
assertEquals(State. TERMINATED, service.state()); 


} 


public void testNoOpServiceStopIdempotenceDoubleWait() throws 
NoOpService service = new NoOpService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync().awaitTerminated(); 
service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


} 


public void testNoOpServiceStartStopAndwaitUninterruptible( ) 
throws Exception { 
NoOpService service = new NoOpService(); 


currentThread().interrupt(); 

try { 

service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


assertTrue(currentThread().isInterrupted()); 

} finally { 

Thread.interrupted(); // clear interrupt for future tests 
} 

} 


private static class NoOpService extends AbstractService { 
boolean running = false; 


Excer 


@Override protected void doStart() { 
assertFalse(running); 
running = true; 
notifyStarted(); 
} 


@Override protected void doStop() { 
assertTrue(running); 
running = false; 
notifyStopped(); 
} 
} 


public void testManualServiceStartStop() throws Exception { 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 
assertEquals(State.STARTING, service.state()); 
assertFalse(service.isRunning()); 
assertTrue(service.doStartCalled); 


service.notifyStarted(); // usually this would be invoked by anothe 
assertEquals(State.RUNNING, service.state()); 
assertTrue(service.isRunning()); 


service.stopAsync(); 
assertEquals(State.STOPPING, service.state()); 
assertFalse(service.isRunning()); 
assertTrue(service.doStopCalled) ; 


service.notifyStopped(); // usually this would be invoked by anothe 
assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 

assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.STOPPING, 

State.TERMINATED), 

listener.getStateHistory()); 


} 


public void testManualServiceNotifyStoppedwhileRunning() throws Ex 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 

service.notifyStarted(); 
service.notifyStopped(); 

assertEquals(State. TERMINATED, service.state()); 


assertFalse(service.isRunning()); 
assertFalse(service.doStopCalled); 


assertEquals( 
ImmutableList.of( 
State.STARTING, 
State.RUNNING, 

State. TERMINATED), 
listener.getStateHistory()); 


} 


public void testManualServiceStopwhileStarting() throws Exception : 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 
assertEquals(State.STARTING, service.state()); 
assertFalse(service.isRunning()); 
assertTrue(service.doStartCalled); 


service.stopAsync(); 
assertEquals(State.STOPPING, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service.doStopCalled); 


service.notifyStarted(); 
assertEquals(State.STOPPING, service.state()); 
assertFalse(service.isRunning()); 
assertTrue(service.doStopCalled) ; 


service.notifyStopped(); 

assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 

assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.STOPPING, 

State. TERMINATED), 

listener.getStateHistory()); 


} 


JER 
* This tests for a bug where if {@link Service#stopAsync()} was cé 
* {@link State#STARTING} more than once, the {@link Listener#stopy 
* called multiple times. 
a 
public void testManualServiceStopMultipleTimeswhileStarting() thr 
ManualSwitchedService service = new ManualSwitchedService(); 
final AtomicInteger stopppingCount = new AtomicInteger(); 
service.addListener(new Listener() { 
@Override public void stopping(State from) { 
stopppingCount.incrementAndGet(); 


}, MoreExecutors.sameThreadExecutor()); 


service.startAsync(); 
service.stopAsync(); 
assertEquals(1, stopppingCount.get()); 
service.stopAsync(); 
assertEquals(1, stopppingCount.get()); 


} 


public void testManualServiceStopwhileNew() throws Exception { 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 


service.stopAsync(); 

assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service.doStartCalled); 
assertFalse(service.doStopCalled); 
assertEquals(ImmutableList.of(State. TERMINATED), listener.getState 


} 


public void testManualServiceFailwhileStarting() throws Exception : 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 
service.startAsync(); 

service.notifyFailed(EXCEPTION) ; 
assertEquals(ImmutableList.of(State.STARTING, State.FAILED), liste 


} 


public void testManualServiceFailWhileRunning() throws Exception { 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 
service.startAsync(); 

service.notifyStarted(); 

service.notifyFailed(EXCEPTION) ; 
assertEquals(ImmutableList.of(State.STARTING, State.RUNNING, State 
listener.getStateHistory()); 


} 


public void testManualServiceFailwhileStopping() throws Exception : 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener listener = RecordingListener.record(service); 
service.startAsync(); 

service.notifyStarted(); 

service.stopAsync(); 

service.notifyFailed(EXCEPTION) ; 
assertEquals(ImmutableList.of(State.STARTING, State.RUNNING, State 
listener.getStateHistory()); 


} 


public void testManualServiceUnrequestedStop() { 
ManualSwitchedService service = new ManualSwitchedService(); 


service.startAsync(); 


service.notifyStarted(); 
assertEquals(State.RUNNING, service.state()); 
assertTrue(service.isRunning()); 
assertFalse(service.doStopCalled); 


service.notifyStopped(); 

assertEquals(State. TERMINATED, service.state()); 
assertFalse(service.isRunning()); 
assertFalse(service.doStopCalled); 


} 


Ce 
* The user of this service should call {@link #notifyStarted} and 
* #notifyStopped} after calling {@link #startAsync} and {@link #s1 
y 
private static class ManualSwitchedService extends AbstractService 
boolean doStartCalled = false; 
boolean doStopCalled = false; 


@Override protected void doStart() { 
assertFalse(doStartCalled); 
doStartCalled = true; 


} 


@Override protected void doStop() { 
assertFalse(doStopCalled); 
doStopCalled = true; 

} 
} 


public void testAwaitTerminated() throws Exception { 
final NoOpService service = new NoOpService(); 
Thread waiter = new Thread() { 

@Override public void run() { 
service.awaitTerminated(); 

} 

}; 

waiter.start(); 
service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 
service.stopAsync(); 

waiter.join(100); // ensure that the await in the other thread is 
assertFalse(waiter.isAlive()); 


} 


public void testAwaitTerminated_FailedService() throws Exception { 
final ManualSwitchedService service = new ManualSwitchedService(), 
final AtomicReference<Throwable> exception = Atomics.newReference| 
Thread waiter = new Thread() { 
@Override public void run() { 


try { 


service.awaitTerminated(); 

fail("Expected an IllegalStateException"); 

} catch (Throwable t) { 

exception.set(t); 

} 

} 

}; 

waiter.start(); 

service.startAsync(); 

service.notifyStarted(); 

assertEquals(State.RUNNING, service.state()); 
service.notifyFailed(EXCEPTION); 
assertEquals(State.FAILED, service.state()); 
waiter.join(100); 

assertFalse(waiter.isAlive()); 
assertTrue(exception.get() instanceof IllegalStateException); 
assertEquals(EXCEPTION, exception.get().getCause()); 


} 


public void testThreadedServiceStartAndwaitStopAndwait() throws Thi 
ThreadedService service = new ThreadedService(); 

RecordingListener listener = RecordingListener.record(service); 
service.startAsync().awaitRunning(); 

assertEquals(State.RUNNING, service.state()); 


service.awaitRunChecks(); 


service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


throwIfSet(thrownByExecutionThread) ; 
assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.STOPPING, 

State. TERMINATED), 
listener.getStateHistory()); 


} 


public void testThreadedServiceStopIdempotence() throws Throwable : 
ThreadedService service = new ThreadedService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.awaitRunChecks()j; 
service.stopAsync(); 
service.stopAsync().awaitTerminated(); 


assertEquals(State. TERMINATED, service.state()); 


throwIfSet(thrownByExecutionThread) ; 


} 


public void testThreadedServiceStopIdempotenceAfterwait () 
throws Throwable { 
ThreadedService service = new ThreadedService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.awaitRunChecks(); 


service.stopAsync().awaitTerminated(); 
service.stopAsync(); 
assertEquals(State. TERMINATED, service.state()); 


executionThread.join(); 


throwIfSet(thrownByExecutionThread) ; 
} 


public void testThreadedServiceStopIdempotenceDoublewait() 
throws Throwable { 
ThreadedService service = new ThreadedService(); 


service.startAsync().awaitRunning(); 
assertEquals(State.RUNNING, service.state()); 


service.awaitRunChecks(); 


service.stopAsync().awaitTerminated(); 
service.stopAsync().awaitTerminated(); 
assertEquals(State. TERMINATED, service.state()); 


throwIfSet(thrownByExecutionThread) ; 
} 


public void testManualServiceFailureIdempotence() { 
ManualSwitchedService service = new ManualSwitchedService(); 
RecordingListener.record(service); 
service.startAsync(); 

service.notifyFailed(new Exception("1")); 
service.notifyFailed(new Exception("2")); 
assertEquals("1", service.failureCause().getMessage()); 
try { 

service.awaitRunning(); 

fail(); 

} catch (IllegalStateException e) { 

assertEquals("1", e.getCause().getMessage()); 

} 

} 


private class ThreadedService extends AbstractService { 
final CountDownLatch hasConfirmedIsRunning = new CountDownLatch(1. 


* The main test thread tries to stop() the service shortly after 
* confirming that it is running. Meanwhile, the service itself is 
* to confirm that it is running. If the main thread's stop() call 
* before it has the chance, the test will fail. To avoid this, the 
* thread calls this method, which waits until the service has pert 
* its own "running" check. 


void awaitRunChecks() throws InterruptedException { 
assertTrue("Service thread hasn't finished its checks. " 


+ "Exception status (possibly stale): " + thrownByExecutionThread, 
hasConfirmedIsRunning.await(10, SECONDS) ); 
} 


@Override protected void doStart() { 
assertEquals(State.STARTING, state()); 
invokeOnExecutionThreadForTest(new Runnable() { 
@Override public void run() { 
assertEquals(State.STARTING, state()); 
notifyStarted(); 
assertEquals(State.RUNNING, state()); 
hasConfirmedIsRunning.countDown(); 

} 
}); 
} 


@Override protected void doStop() { 
assertEquals(State.STOPPING, state()); 
invokeOnExecutionThreadForTest(new Runnable() { 
@Override public void run() { 
assertEquals(State.STOPPING, state()); 
notifyStopped(); 
assertEquals(State.TERMINATED, state()); 
} 

}); 
} 
} 


private void invokeOnExecutionThreadForTest(Runnable runnable) { 
executionThread = new Thread(runnable); 
executionThread.setUncaughtExceptionHandler(new UncaughtExceptiont 
@Override 

public void uncaughtException(Thread thread, Throwable e) { 
thrownByExecutionThread = e; 

} 

}); 


executionThread.start(); 


} 


private static void throwIfSet(Throwable t) throws Throwable { 
if (t != null) { 
throw t; 


} 
} 


public void testStopUnstartedService() throws Exception { 
NoOpService service = new NoOpService(); 
RecordingListener listener = RecordingListener.record(service); 


service.stopAsync(); 
assertEquals(State. TERMINATED, service.state()); 


try { 
service.startAsync(); 


fail(); 
} catch (IllegalStateException expected) {} 
assertEquals(State. TERMINATED, Iterables.getOnlyElement(listener.¢ 


} 


public void testFailingServiceStartAndwait() throws Exception { 
StartFailingService service = new StartFailingService(); 
RecordingListener listener = RecordingListener.record(service); 


try { 
service.startAsync().awaitRunning(); 


fail(); 

} catch (IllegalStateException e) { 
assertEquals(EXCEPTION, service.failureCause()); 
assertEquals(EXCEPTION, e.getCause()); 

} 

assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.FAILED), 

listener.getStateHistory()); 


} 


public void testFailingServiceStopAndWait_stopFailing() throws Exce 
StopFailingService service = new StopFailingService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync().awaitRunning(); 

try { 

service.stopAsync().awaitTerminated(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(EXCEPTION, service.failureCause()); 
assertEquals(EXCEPTION, e.getCause()); 


assertEquals( 
ImmutableList.of( 
State.STARTING, 
State.RUNNING, 
State.STOPPING, 
State.FAILED), 


listener.getStateHistory()); 
} 


public void testFailingServiceStopAndWait_runFailing() throws Excey 
RunFailingService service = new RunFailingService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 

try { 

service.awaitRunning(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(EXCEPTION, service.failureCause()); 
assertEquals(EXCEPTION, e.getCause()); 


assertEquals ( 
ImmutableList.of( 
State.STARTING, 
State.RUNNING, 
State.FAILED), 
listener.getStateHistory()); 


} 


public void testThrowingServiceStartAndwait() throws Exception { 
StartThrowingService service = new StartThrowingService(); 
RecordingListener listener = RecordingListener.record(service); 


try { 
service.startAsync().awaitRunning(); 


fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.exception, service.failureCause()); 
assertEquals(service.exception, e.getCause()); 

} 

assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.FAILED), 

listener.getStateHistory()); 


} 


public void testThrowingServiceStopAndwait_stopThrowing() throws E> 
StopThrowingService service = new StopThrowingService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync().awaitRunning(); 

try { 

service.stopAsync().awaitTerminated(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.exception, service. failureCause()); 
assertEquals(service.exception, e.getCause()); 


} 


assertEquals( 
ImmutableList. of ( 
State.STARTING, 
State.RUNNING, 
State.STOPPING, 
State.FAILED), 

listener .getStateHistory()); 


} 


public void testThrowingServiceStopAndwait_runThrowing() throws Ex 
RunThrowingService service = new RunThrowingService(); 
RecordingListener listener = RecordingListener.record(service); 


service.startAsync(); 

try { 

service.awaitTerminated(); 

fail(); 

} catch (IllegalStateException e) { 
assertEquals(service.exception, service.failureCause()); 
assertEquals(service.exception, e.getCause()); 
} 

assertEquals( 

ImmutableList.of( 

State.STARTING, 

State.RUNNING, 

State.FAILED), 

listener.getStateHistory()); 


} 


public void testFailureCause_throwsIfNotFailed() { 
StopFailingService service = new StopFailingService(); 
TA i 

service. failureCause(); 

fail(); 

} catch (IllegalStateException e) { 

// expected 

} 

service.startAsync().awaitRunning(); 

try { 

service. failureCause(); 

fail(); 

} catch (IllegalStateException e) { 

// expected 

} 


try { 
service.stopAsync().awaitTerminated(); 


fail(); 

} catch (IllegalStateException e) { 
assertEquals(EXCEPTION, service.failureCause()); 
assertEquals(EXCEPTION, e.getCause()); 


} 
} 


public void testAddListenerAfterFailureDoesntCauseDeadlock() throws 
final StartFailingService service = new StartFailingService(); 
service.startAsync(); 

assertEquals(State.FAILED, service.state()); 
service.addListener(new RecordingListener(service), MoreExecutors 
Thread thread = new Thread() { 

@Override public void run() { 

// Internally stopAsync() grabs a lock, this could be any such met 
service.stopAsync(); 

} 

}; 

thread.start(); 

thread. join(100); 

assertFalse(thread + " is deadlocked", thread.isAlive()); 


} 


public void testListenerDoesntDeadlockOnStartAndwaitFromRunning() 1 
final NoOpThreadedService service = new NoOpThreadedService(); 
service.addListener(new Listener() { 

@Override public void running() { 

service.awaitRunning(); 

} 

}, MoreExecutors.sameThreadExecutor()); 
service.startAsync().awaitRunning(10, TimeUnit.MILLISECONDS); 
service.stopAsync(); 


} 


public void testListenerDoesntDeadlockOnStopAndWaitFromTerminated(_ 
final NoOpThreadedService service = new NoOpThreadedService(); 
service.addListener(new Listener() { 

@Override public void terminated(State from) { 
service.stopAsync().awaitTerminated(); 

} 

}, MoreExecutors.sameThreadExecutor()); 
service.startAsync().awaitRunning(); 


Thread thread = new Thread() { 

@Override public void run() { 
service.stopAsync().awaitTerminated(); 

} 

}; 

thread.start(); 

thread. join(100); 

assertFalse(thread + " is deadlocked", thread.isAlive()); 


} 


private static class NoOpThreadedService extends AbstractExecution 
final CountDownLatch latch = new CountDownLatch(1); 

@Override protected void run() throws Exception { 

latch.await(); 

} 

@Override protected void triggerShutdown() { 

latch.countDown(); 


} 
} 


private static class StartFailingService extends AbstractService { 
@Override protected void doStart() { 
notifyFailed(EXCEPTION); 


} 


@Override protected void doStop() { 
fail(); 
} 
} 


private static class RunFailingService extends AbstractService { 
@Override protected void doStart() { 

notifyStarted(); 

notifyFailed(EXCEPTION); 


} 


@Override protected void doStop() { 
fail(); 
} 
} 


private static class StopFailingService extends AbstractService { 
@Override protected void doStart() { 
notifyStarted(); 


} 


@Override protected void doStop() { 
notifyFailed(EXCEPTION); 


} 
} 


private static class StartThrowingService extends AbstractService : 
final RuntimeException exception = new RuntimeException("deliberate 


@Override protected void doStart() { 
throw exception; 


} 


@Override protected void doStop() { 
fail(); 
} 
} 


private static class RunThrowingService extends AbstractService { 
final RuntimeException exception = new RuntimeException("deliberate 


@Override protected void doStart() { 
notifyStarted(); 


throw exception; 


} 


@Override protected void doStop() { 
fail(); 
} 
} 


private static class StopThrowingService extends AbstractService { 
final RuntimeException exception = new RuntimeException("deliberate 


@Override protected void doStart() { 
notifyStarted(); 


} 


@Override protected void doStop() { 
throw exception; 
} 
} 


private static class RecordingListener extends Listener { 

static RecordingListener record(Service service) { 
RecordingListener listener = new RecordingListener(service); 
service.addListener(listener, MoreExecutors.sameThreadExecutor()), 
return listener; 


} 


final Service service; 


RecordingListener(Service service) { 
this.service = service; 


} 


@GuardedBy( "this" ) 
final List<State> stateHistory = Lists.newArrayList(); 
final CountDownLatch completionLatch = new CountDownLatch(1)j; 


ImmutableList<State> getStateHistory() throws Exception { 
completionLatch.await(); 

synchronized (this) { 

return ImmutableList.copyOf(stateHistory); 

} 

} 


@Override public synchronized void starting() { 
assertTrue(stateHistory.isEmpty()); 
assertNotSame(State.NEW, service.state()); 
stateHistory.add(State.STARTING); 


} 


@Override public synchronized void running() { 
assertEquals(State.STARTING, Iterables.getOnlyElement(stateHistor\ 


stateHistory.add(State.RUNNING); 
service.awaitRunning(); 
assertNotSame(State.STARTING, service.state()); 


} 


@Override public synchronized void stopping(State from) { 
assertEquals(from, Iterables.getLast(stateHistory) ); 
stateHistory.add(State.STOPPING) ; 
if (from == State.STARTING) { 
try { 
service.awaitRunning(); 
fail(); 

} catch (IllegalStateException expected) { 
assertNull(expected.getCause()); 
assertTrue(expected.getMessage( ) .equals( 

"Expected the service to be RUNNING, but was STOPPING")); 
} 

} 


assertNotSame(from, service.state()); 


} 


@Override public synchronized void terminated(State from) { 
assertEquals(from, Iterables.getLast(stateHistory, State.NEw)); 
stateHistory.add(State. TERMINATED); 
assertEquals(State. TERMINATED, service.state()); 
if (from == State.NEW) { 
try { 
service.awaitRunning(); 
fail(); 

} catch (IllegalStateException expected) { 
assertNull(expected.getCause()); 
assertTrue(expected.getMessage( ) .equals( 

"Expected the service to be RUNNING, but was TERMINATED") ); 
} 

} 


completionLatch.countDown(); 


} 


@Override public synchronized void failed(State from, Throwable fa: 
assertEquals(from, Iterables.getLast(stateHistory) ); 
stateHistory.add(State.FAILED); 
assertEquals(State.FAILED, service.state()); 
assertEquals(failure, service.failureCause()); 
if (from == State.STARTING) { 
try { 
service.awaitRunning(); 
fail(); 

} catch (IllegalStateException e) { 
assertEquals(failure, e.getCause()); 
} 
} 


try { 
service.awaitTerminated(); 


fail(); 

} catch (IllegalStateException e) { 
assertEquals(failure, e.getCause()); 
} 

completionLatch.countDown(); 

} 

} 


public void testNotifyStartedwhenNotStarting() { 
AbstractService service = new DefaultService(); 
try { 

service.notifyStarted(); 

fail(); 

} catch (IllegalStateException expected) {} 

} 


public void testNotifyStoppedwhenNotRunning() { 
AbstractService service = new DefaultService(); 
try { 

service.notifyStopped(); 

fail(); 

} catch (IllegalStateException expected) {} 

} 


public void testNotifyFailedwhenNotStarted() { 
AbstractService service = new DefaultService(); 
try { 

service.notifyFailed(new Exception()); 

fail(); 

} catch (IllegalStateException expected) {} 

} 


public void testNotifyFailedwhenTerminated() { 
NoOpService service = new NoOpService(); 
service.startAsync().awaitRunning(); 
service.stopAsync().awaitTerminated(); 

try { 

service.notifyFailed(new Exception()); 
fail(); 

} catch (IllegalStateException expected) {} 

} 


private static class DefaultService extends AbstractService { 
@Override protected void doStart() {} 

@Override protected void doStop() {} 

} 


private static final Exception EXCEPTION = new Exception(); 


} 
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* Tests for {@link ServiceManager}. 
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* @author Luke Sandberg 
* @author Chris Nokleberg 


wh 


public class ServiceManagerTest extends TestCase { 


private static class NoOpService extends AbstractService { 
@Override protected void doStart() { 
notifyStarted(); 


} 


@Override protected void doStop() { 
notifyStopped(); 
} 
} 


jp 

* A NoOp service that will delay the startup and shutdown notificé 
* of time. 

i 

private static class NoOpDelayedSerivce extends NoOpService { 
private long delay; 


public NoOpDelayedSerivce(long delay) { 
this.delay = delay; 


} 


@Override protected void doStart() { 

new Thread() { 

@Override public void run() { 
Uninterruptibles.sleepUninterruptibly(delay, TimeUnit .MILLISECONDS 
notifyStarted(); 

} 

}.start(); 

} 


@Override protected void doStop() { 

new Thread() { 

@Override public void run() { 
Uninterruptibles.sleepUninterruptibly(delay, TimeUnit .MILLISECONDS 
notifyStopped(); 

} 

}.start(); 

} 

} 


private static class FailStartService extends NoOpService { 
@Override protected void doStart() { 

notifyFailed(new IllegalStateException("failed")); 

} 

} 


private static class FailRunService extends NoOpService { 
@Override protected void doStart() { 

super .doStart(); 

notifyFailed(new IllegalStateException("failed")); 

} 

} 


private static class FailStopService extends NoOpService { 
@Override protected void doStop() { 

notifyFailed(new IllegalStateException("failed")); 

} 

} 


public void testServiceStartupTimes() { 

Service a = new NoOpDelayedSerivce(150); 

Service b = new NoOpDelayedSerivce(353) ; 

ServiceManager serviceManager = new ServiceManager(asList(a, b)); 
serviceManager.startAsync().awaitHealthy(); 

ImmutableMap<Service, Long> startupTimes = serviceManager.startup 
assertEquals(2, startupTimes.size()); 
assertTrue(startupTimes.get(a) >= 150); 
assertTrue(startupTimes.get(b) >= 353); 


} 


public void testServiceStartStop() { 

Service a = new NoOpService(); 

Service b = new NoOpService(); 

ServiceManager manager = new ServiceManager(asList(a, b)); 
RecordingListener listener = new RecordingListener(); 
manager .addListener(listener); 

assertState(manager, Service.State.NEW, a, b); 
assertFalse(manager.isHealthy()); 

manager .startAsync().awaitHealthy(); 
assertState(manager, Service.State.RUNNING, a, b); 
assertTrue(manager.isHealthy()); 
assertTrue(listener.healthyCalled); 
assertFalse(listener.stoppedCalled) ; 
assertTrue(listener.failedServices.isEmpty()); 
manager .stopAsync().awaitStopped(); 
assertState(manager, Service.State.TERMINATED, a, b); 
assertFalse(manager.isHealthy()); 
assertTrue(listener.stoppedCalled); 
assertTrue(listener.failedServices.isEmpty()); 


} 


public void testFailStart() throws Exception { 

Service a = new NoOpService(); 

Service b = new FailStartService(); 

Service c = new NoOpService(); 

Service d = new FailStartService(); 

Service e = new NoOpService(); 

ServiceManager manager = new ServiceManager(asList(a, b, c, d, e) 
RecordingListener listener = new RecordingListener(); 
manager .addListener(listener); 

assertState(manager, Service.State.NEW, a, b, c, d, e); 
try { 

manager .startAsync().awaitHealthy(); 

fail(); 

} catch (IllegalStateException expected) { 


} 

assertFalse(listener.healthyCalled); 

assertState(manager, Service.State.RUNNING, a, c, e); 
assertEquals(ImmutableSet.of(b, d), listener.failedServices) ; 
assertState(manager, Service.State.FAILED, b, d); 
assertFalse(manager.isHealthy()); 


manager .stopAsync().awaitStopped(); 
assertFalse(manager.isHealthy()); 
assertFalse(listener.healthyCalled) ; 
assertTrue(listener.stoppedCalled); 


} 


public void testFailRun() throws Exception { 

Service a = new NoOpService(); 

Service b = new FailRunService(); 

ServiceManager manager = new ServiceManager(asList(a, b)); 
RecordingListener listener = new RecordingListener(); 
manager .addListener(listener); 

assertState(manager, Service.State.NEW, a, b); 

try { 

manager .startAsync().awaitHealthy(); 

fail(); 

} catch (IllegalStateException expected) { 

} 

assertTrue(listener.healthyCalled); 
assertEquals(ImmutableSet.of(b), listener .failedServices); 


manager .stopAsync().awaitStopped(); 
assertState(manager, Service.State.FAILED, b); 
assertState(manager, Service.State.TERMINATED, a); 


assertTrue(listener.stoppedCalled); 


} 


public void testFailStop() throws Exception { 

Service a = new NoOpService(); 

Service b = new FailStopService(); 

Service c = new NoOpService(); 

ServiceManager manager = new ServiceManager(asList(a, b, c)); 
RecordingListener listener = new RecordingListener(); 

manager .addListener(listener); 


manager .startAsync().awaitHealthy(); 
assertTrue(listener.healthyCalled); 
assertFalse(listener.stoppedCalled) ; 
manager .stopAsync().awaitStopped(); 


assertTrue(listener.stoppedCalled) ; 
assertEquals(ImmutableSet.of(b), listener.failedServices); 
assertState(manager, Service.State.FAILED, b); 
assertState(manager, Service.State.TERMINATED, a, C); 

} 


public void testToString() throws Exception { 

Service a = new NoOpService(); 

Service b = new FailStartService(); 

ServiceManager manager = new ServiceManager(asList(a, b)); 
String toString = manager.toString(); 
assertTrue(toString.contains("NoOpService")); 
assertTrue(toString.contains("FailStartService") ); 


} 


public void testTimeouts() throws Exception { 

Service a = new NoOpDelayedSerivce(50); 

ServiceManager manager = new ServiceManager(asList(a)); 
manager.startAsync(); 

try { 

manager .awaitHealthy(1, TimeUnit.MILLISECONDS) ; 

fail(); 

} catch (TimeoutException expected) { 


} 
manager .awaitHealthy(100, TimeUnit.MILLISECONDS); // no exception 


manager .stopAsync(); 

try { 

manager .awaitStopped(1, TimeUnit.MILLISECONDS) ; 
fail( ); 

} catch (TimeoutException expected) { 


} 
manager .awaitStopped(100, TimeUnit.MILLISECONDS); // no exception 


} 


Vokes 

* This covers a case where if the last service to stop failed ther 
* never be called. 

ag 

public void testSingleFailedServiceCallsStopped() { 
Service a = new FailStartService(); 

ServiceManager manager = new ServiceManager(asList(a)); 
RecordingListener listener = new RecordingListener(); 
manager .addListener(listener); 

try { 

manager .startAsync().awaitHealthy(); 

fail(); 

} catch (IllegalStateException expected) { 

} 


assertTrue(listener.stoppedCalled); 


} 


JE 

* This covers a bug where listener.healthy would get called when ¢ 
* startup (it occurred in more complicated cases also). 

oe 

public void testFailStart_singleServiceCallsHealthy() { 

Service a = new FailStartService(); 


ServiceManager manager = new ServiceManager(asList(a)); 
RecordingListener listener = new RecordingListener(); 
manager .addListener(listener); 

try { 

manager .startAsync().awaitHealthy(); 

fail(); 

} catch (IllegalStateException expected) { 


} 
assertFalse(listener.healthyCalled) ; 


} 


[pr 

* This covers a bug where if a listener was installed that would : 
* fails and something failed during startup before service.start v 
* then awaitStopped would deadlock due to an IllegalStateExceptior 
* stop the timer(!). 

a 

public void testFailStart_stopOthers() throws TimeoutException { 
Service a = new FailStartService(); 

Service b = new NoOpService(); 

final ServiceManager manager = new ServiceManager(asList(a, b)); 
manager .addListener(new Listener() { 

@Override public void failure(Service service) { 

manager .stopAsync(); 

th); 

manager.startAsync(); 

manager .awaitStopped(10, TimeUnit .MILLISECONDS) ; 


} 
private static void assertState( 
ServiceManager manager, Service.State state, Service... services) 


Collection<Service> managerServices = manager.servicesByState() .dg 
for (Service service : services) { 
assertEquals(service.toString(), state, service.state()); 


assertEquals(service.toString(), service.isRunning(), state == Se) 
assertTrue(managerServices + " should contain " + service, manage) 
} 

} 
JEE 


* This is for covering a case where the ServiceManager would behai 
* with no service under management. Listeners would never fire bec 
* healthy and stopped at the same time. This test ensures that li: 
* makes sense. 

wi 

public void testEmptyServiceManager() { 

Logger logger = Logger.getLogger(ServiceManager.class.getName()); 
logger .setLevel(Level.FINEST); 

TestLogHandler logHandler = new TestLogHandler(); 

logger .addHandler(logHandler ); 

ServiceManager manager = new ServiceManager(Arrays.<Service>asLis1 
RecordingListener listener = new RecordingListener(); 

manager .addListener(listener, MoreExecutors.sameThreadExecutor()), 


manager .startAsync().awaitHealthy(); 
assertTrue(manager.isHealthy()); 
assertTrue(listener.healthyCalled); 
assertFalse(listener.stoppedCalled) ; 
assertTrue(listener.failedServices.isEmpty()); 

manager .stopAsync().awaitStopped(); 
assertFalse(manager.isHealthy()); 
assertTrue(listener.stoppedCalled); 
assertTrue(listener.failedServices.isEmpty()); 

// check that our NoOpService is not directly observable via any ( 
// via logging. 

assertEquals("ServiceManager {services=[]}", manager.toString()); 
assertTrue(manager.servicesByState().isEmpty()); 
assertTrue(manager.startupTimes().isEmpty()); 

Formatter logFormatter = new Formatter() { 

@Override public String format(LogRecord record) { 

return formatMessage(record); 

} 

}; 

for (LogRecord record : logHandler.getStoredLogRecords()) { 
assertFalse(logFormatter.format(record).contains("NoOpService") ); 
} 

} 


JERS 
* This is for a case where a long running Listener using the same 
* another thread calling stopAsync(). 
ie 


public void testListenerDeadlock() throws InterruptedException { 
final CountDownLatch failEnter = new CountDownLatch(1); 
Service failRunService = new AbstractService() { 
@Override protected void doStart() { 

new Thread() { 

@Override public void run() { 

notifyStarted(); 

notifyFailed(new Exception("boom")); 

} 

}.start(); 

} 

@Override protected void doStop() { 

notifyStopped(); 

} 

}; 

final ServiceManager manager = new ServiceManager ( 
Arrays.asList(failRunService, new NoOpService())); 
manager ..addListener(new ServiceManager.Listener() { 
@Override public void failure(Service service) { 
failEnter.countDown(); 

// block forever! 
Uninterruptibles.awaitUninterruptibly(new CountDownLatch(1)); 


} 


}, MoreExecutors.sameThreadExecutor()); 


// We do not call awaitHealthy because, due to races, that method 
// we really just want to wait for the thread to be in the failure 
// explicitly instead. 

manager.startAsync(); 

failEnter.await(); 

assertFalse("State should be updated before calling listeners", mé 
// now we want to stop the services. 

Thread stoppingThread = new Thread() { 

@Override public void run() { 

manager .stopAsync().awaitStopped(); 

} 

}; 

stoppingThread.start(); 

// this should be super fast since the only non stopped service i: 
stoppingThread.join(1000); 

assertFalse("stopAsync has deadlocked!.", stoppingThread.isAlive(` 


} 


JAn 

* Catches a bug where when constructing a service manager failed, 
* service could cause IllegalStateExceptions inside the partially 
* This ISE wouldn't actually bubble up but would get logged by Exe 
* the original error (which was not constructing ServiceManager cc 
ys 

public void testPartiallyConstructedManager() { 

Logger logger = Logger.getLogger("global"); 

logger .setLevel(Level.FINEST); 

TestLogHandler logHandler = new TestLogHandler(); 

logger .addHandler(logHandler ); 

NoOpService service = new NoOpService(); 

service.startAsync(); 

try { 

new ServiceManager(Arrays.asList(service)); 

fail(); 

} catch (IllegalArgumentException expected) {} 
service.stopAsync(); 

// Nothing was logged! 

assertEquals(0, logHandler.getStoredLogRecords().size()); 


} 


public void testPartiallyConstructedManager_transitionAfterAddListe 
// The implementation of this test is pretty sensitive to the imp: 
// ensure that if weird things happen during construction then we 
final NoOpService servicei = new NoOpService(); 
// This service will start service1 when addListener is called. TI 
// started asynchronously. 
Service service2 = new Service() { 
final NoOpService delegate = new NoOpService(); 
@Override public final void addListener(Listener listener, Executc 
service1.startAsync(); 
delegate.addListener(listener, executor); 


} 


// Delegates from here on down 


@Override public final Service startAsync() { 


return delegate. 


} 


@Override public 


return delegate. 


} 


@Override public 


return delegate. 


} 


@Override public 


return delegate. 


} 


@Override public 


return delegate. 


} 


@Override public 


return delegate. 


} 


@Override public 


startAsync(); 


final Service stopAsync() { 
stopAsync(); 


final ListenableFuture<State> start() { 
start(); 


final ListenableFuture<State> stop() { 
stop(); 


State startAndwait() { 
startAndwait(); 


State stopAndwait() { 
stopAndwait(); 


final void awaitRunning() { 


delegate.awaitRunning(); 


} 


@Override public 


final void awaitRunning(long timeout, TimeUnit un: 


throws TimeoutException { 
delegate.awaitRunning(timeout, unit); 


} 


@Override public 


final void awaitTerminated() { 


delegate.awaitTerminated(); 


} 


@Override public 


final void awaitTerminated(long timeout, TimeUnit 


throws TimeoutException { 
delegate.awaitTerminated(timeout, unit); 


} 


@Override public 


return delegate. 


} 


@Override public 


return delegate. 


} 


@Override public 


return delegate. 


} 


final boolean isRunning() { 
isRunning(); 


final State state() { 
state(); 


final Throwable failureCause() { 
failureCause(); 


new ServiceManager(Arrays.asList(service1, service2)); 

fail(); 

} catch (IllegalArgumentException expected) { 
assertTrue(expected.getMessage().contains("started transitioning «é 


* 

* This test is for a case where two Service.Listener callbacks fot 
* transitionService in the wrong order due to a race. Due to the 1 
* test isn't guaranteed to expose the issue, but it is at least 1: 
* race sneaks back in, and in this case flaky means something is ( 
* 
* 


<p>Before the bug was fixed this test would fail at least 30% oł 


public void testTransitionRace() throws TimeoutException { 
for (int k = 0; k < 1000; k++) { 

List<Service> services = Lists.newArrayList(); 

wor (aume i s Oe ade Sie i 

services.add(new SnappyShutdownService(i)); 

} 

ServiceManager manager = new ServiceManager (services); 
manager .startAsync().awaitHealthy(); 

manager .stopAsync().awaitStopped(1, TimeUnit.SECONDS); 
} 

} 


ea 

* This service will shutdown very quickly after stopAsync is calle 
* so that we know that the stopping() listeners will execute ona 
* terminated() listeners. 

Ey 

private static class SnappyShutdownService extends AbstractExecut: 
final int index; 

final CountDownLatch latch = new CountDownLatch(1); 


SnappyShutdownService(int index) { 
this.index = index; 


} 


@Override protected void run() throws Exception { 
latch.await(); 


} 


@Override protected void triggerShutdown() { 
latch.countDown(); 


} 


@Override protected String serviceName() { 
return this.getClass().getSimpleName() + "[" + index + "]"; 


} 
} 


public void testNulls() { 

ServiceManager manager = new ServiceManager(Arrays.<Service>asLis1 
new NullPointerTester() 

.setDefault(ServiceManager.Listener.class, new RecordingListener(. 
.testAllPublicInstanceMethods(manager ); 


} 


private static final class RecordingListener extends ServiceManage} 
volatile boolean healthyCalled; 

volatile boolean stoppedCalled; 

final Set<Service> failedServices = Sets.newConcurrentHashSet(); 


@Override public void healthy() { 
healthyCalled = true; 


} 


@Override public void stopped() { 
stoppedCalled = true; 


} 


@Override public void failure(Service service) { 
failedServices.add(service) ; 





6- 字 符 串 处 理 : pall, eR, JAI 


原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : 丁 一 


连接 器 [Joiner] 


用 分 隔 符 把 字符 串 序列 连接 起 来 也 可 能 会 遇 上 不 必要 的 麻烦 。 如 果 字 符 串 序列 中 含 
有 null， 那 连接 操作 会 更 难 。Fluent 风 格 的 Joiner 让 连接 字符 串 更 简单 。 


Joiner joiner = Joiner.on("; ").skipNulls(); 
return joiner.join("Harry", null, "Ron", "Hermione"); 


上 述 代 码 返 回 "Harry; Ron; Hermione”, 另外 ，useForNull(String) 方 法 可 以 给 定 某 
个 字符 串 来 蔡 换 null， 而 不 像 skipNulls() 方 法 是 直接 忽略 null。 Joiner 也 可 以 用 来 连 
接 对 象 类 型 ， 在 这 种 情况 下 ， 它 会 把 对 象 的 toString() 值 连接 起 来 。 


Joiner.on(",").join(Arrays.asList(1, 5, 7)); // returns "1,5,7" 


警告 : joine/ 实 例 总 是 不 可 变 的 。 用 来 定义 joiner 目 标语 义 的 配置 方法 总 会 返回 一 个 
新 的 jojner 实 例 。 这 使 得 joiner 实 例 都 是 线程 安全 的 ， 你 可 以 将 其 定义 fina/ 常 
量 。 


拆 分 器 [Splitter] 


JDK 内 建 的 字符 串 拆 分 工具 有 一 些 古 怪 的 特性 。 上 比如 ，String.split 恰 悄 丢 弃 了 尾部 
的 分 隔 符 。 问题 : ”,a,,b,”.split(“,”) 返 回 ? 


人 

2. null, “a”, null, “b”, null 

3. “a”, null, “b” 

4. “a”, “D” 

5. 以 上 都 不 对 

正确 答 , “a”, “,“b”。 只 有 尾部 的 空 字符 串 被 忽略 了 。 Splitter AD 


reat a a ADAPA 2 EBART 了 完全 的 掌控 。 


Splitter.on(',') 
. trimResults() 
.omitEmptyStrings() 
.Split("foo,bar,, qux"); 


上 述 代 码 返回 lterable<String>， 其 中 包含 foo”、”bar 和 ?qux"。Splitter 可 以 被 设置 
为 按照 任何 模式 、 字 符 、 字 符 串 或 字符 匹配 器 拆 分 。 


拆 分 器 工厂 


方法 


Splitter. 


Splitter. 


Splitter. 


Splitter. 
Splitter. 


Splitter. 


on(char ) 


on(CharMatcher ) 


on(String) 


on(Pattern) 
onPattern(String) 


fixedLength(int ) 


拆 分 器 修饰 符 


B 
党 


SoN 
Si 44s 


范例 


Splitter.on(‘;’) 


Splitter.on(CharMatcher. BREAKING 


Splitter.on(“, “) 


Splitter.onPattern(“\r?\n”) 


Splitter.fixedLength(3) 


方法 描述 
omitEmptyStrings() 从 结果 中 自动 忽略 空 字符 串 
trimResults() 移 除 结 果 字 符 串 的 前 导 空 白 和 尾部 空白 
5 给 定 匹配 器 ， 移 除 结 果 字 符 串 的 前 导 匹 配 字 
trimResults(CharMatcher ) 符 和 尾部 匹配 字符 
limit(int) 限制 拆 分 出 的 字符 串 数量 


如 果 你 想 要 拆 分 器 返回 List， 只 要 使 用 Lists.newArrayList(splitter split(string)) 或 类 似 
警告 : splitter 实 例 总 :是 不 可 变 的 。 用 来 定义 splitter 目 标语 义 的 配置 方法 总 会 

一 个 新 的 splitter 实 例 。 这 使 得 splitter 实 例 都 是 线程 安全 的 ， 你 可 以 将 其 定义 为 
finals. 


字符 匹配 器 [CharMatcher] 


在 以 前 的 Guava 版 本 中 ，StringUtil 类 疯狂 地 膨胀 ， 其 拥有 很 多 处 理 字符 串 的 方法 : 
allAscii、collapse、collapseControlChars、collapseWhitespace、indexOfChars、 
lastIndexNotOf, numSharedChars, removeChars, removeCrLf, 

replaceChars, retainAllChars, strip, stripAndCollapse, stripNonDigits. 所 有 这 
些 方法 指向 两 个 概念 上 的 问题 : 


1. 怎么 才 算 匹配 字符 ? 
2. 如 何 处 理 这 些 匹 配 字符 ? 


为 了 收拾 这 个 泥潭 ， 我 们 开发 了 CharMatcher。 


直观 上 ， 你 可 以 认为 一 个 CharMatcher 实 例 代 表 着 某 一 类 字符 ， 如 数字 或 空白 字 
符 。 事 实 上 来 说 ，CharMatcher 实 例 就 是 k 
也 实现 了 Predicate<Character> 但 类 似 ” 所 有 空白 字符 "或 "所 有 小 写字 母 " 的 需求 
太 普 通 了 ，Guava 因 此 创建 了 这 一 API。 


然而 使 用 CharMatcher 的 好 久 更 在 于 它 提 供 了 一 系列 方法 ， 让 你 对 字符 作 特 定 类 型 
的 操作 : 修剪 [trim]、 折 县 [collapsel]、 移 除 [remove]、 保 留 [retain] 等 等 。 
CharMatcher 实 例 首先 代表 概念 1 : 怎么 才 算 匹配 字符 ? 然后 它 还 提供 了 很 多 操作 概 
念 2 : 如 何 处 理 这 些 匹 配 字符 ?这 样 的 设计 使 得 API 复 末 度 的 线性 增加 可 以 带 来 灵活 
性 和 功能 两 方面 的 增长 。 








String noControl CharMatcher .JAVA_ISO_CONTROL.removeFrom(string) , 

String theDigits = CharMatcher.DIGIT.retainFrom(string); // 只 保留 数 

String spaced = CharMatcher.WHITESPACE.trimAndCollapseFrom(string, 
// 去 除 两 端的 空格 ， 并 把 中 间 的 连续 空格 蔡 换 成 单个 空格 

String noDigits = CharMatcher.JAVA_DIGIT.replaceFrom(string, "*"); 

String lowerAndDigit = CharMatcher.JAVA_DIGIT.or(CharMatcher.JAVA_l 
/ 只 保留 数字 和 小 写字 母 


‘| _— 








注 : CharMatcher 只 人 处理 char 类 型 代表 的 字符 ; 它 不 能 理解 0x10000 到 0x10FFFF 的 
Unicode 增补 字符 。 这 些 逻 辑 字 符 以 代理 对 [surrogate pairs] 的 形式 编码 进 字 符 串 ， 
而 CharMatcher 只 能 将 这 种 逻辑 字符 看 待 成 两 个 独立 的 字符 。 


获取 字符 匹配 器 
CharMatcher 中 的 常量 可 以 满足 大 多 数字 符 匹 配 需求 : 


ANY NONE WHITESPACE 
INVISIBLE DIGIT JAVA_LETTER 
JAVA_LETTER_OR_DIGIT JAVA_ISO_CONTROL JAVA_LOWER_CASE 
ASCII SINGLE_WIDTH 


其 他 获取 字符 匹配 器 的 常见 方法 包括 : 


方法 描述 
E E ES 枚 举 匹 配 字符 。 如 CharMatcheranyOf(aeiou ) 匹 
配 小 写 天 语 元 首 
is(char) 给 定单 一 字符 匹配 。 


给 定 字符 范围 匹配 ， 如 CharMatcher.inRange('‘a’， 
) 


inRange(char, char) 


K 


此 外 ，CharMatcher 还 
有 negate() 、 and(charMatcher) 和 or(CharMatcher) 方法 。 


使 用 字符 匹配 器 


CharMatcher 提 供 了 多 种 多 样 的 方法 操作 CharSequence 中 的 特定 字符 。 其 中 最 常 
用 的 罗列 如 下 : 


方法 描述 
把 每 组 连续 的 匹配 字符 蔡 换 ; 


字符 。 如 
collapseFrom(CharSequence, char) WHITESPACE.collapseFror 
“) 把 字符 串 中 的 连续 空白 字 :! 
为 单个 空格 。 
matchesAll0f (CharSequence) ee rote ail 
removeFrom(CharSequence) 从 字符 序列 中 移 除 所 有 匹配 : 
retainFrom(CharSequence) A 
trimFrom(CharSequence) a 


replaceFrom(CharSequence, CharSequence) 用 特定 字符 序列 替代 匹配 字 


所 有 这 些 方法 返回 String， 除 了 matchesAllOf 返 回 的 是 boolean。 


字符 集 [Charsets] 
不 要 这 样 做 字符 集 处 理 : 


try { 
bytes = string.getBytes("UTF-8"); 

} catch (UnsupportedEncodingException e) { 
// how can this possibly happen? 
throw new AssertionError(e); 


RARES : 
bytes = string.getBytes(Charsets.UTF 8); 


Charsets 针对 所 有 Java 平 台 都 要 保证 支持 的 六 种 字符 集 提 供 了 常量 引用 。 Fix 
使 用 这 些 常量 ， 而 不 是 通过 名 称 获 取 字 符 集 实例 。 


大 小 写 格 式 [CaseFormat] 


CaseFormat 被 用 来 方便 地 在 各 种 ASCII 大 小 写 规范 间 转 换 字 符 串 一 一 比如 ， 编 程 语 
言 的 命名 规范 。CaseFormat 支 持 的 格式 如 下 : 


格式 
LOWER_CAMEL 
LOWER_HYPHEN 
LOWER_UNDERSCORE 
UPPER_CAMEL 


UPPER_UNDERSCORE 


CaseFormat 的 用 法 很 直接 : 


范例 

lowerCamel 
lower-hyphen 
lower_underscore 
UpperCamel 
UPPER_UNDERSCORE 


CaseFormat .UPPER_UNDERSCORE.to(CaseFormat.LOWER_CAMEL, "CONSTANT_N/ 


剧 — B 





我 们 CaseFormat 在 某 些 时 候 尤 其 有 用 ， 比 如 编写 代码 生成 器 的 时 候 。 


T-REX E 


原文 链接 译文 链接 译 者 : 沈 义 扬 ， 校 对 : 丁 一 


概述 


Java 的 原生 类 型 就 是 指 基本 类 型 : byte、short、int、long、float、double、char 和 
boolean。 


在 从 Guava 查 找 原 生 类 型 方法 之 前 ， 可 以 先 查 查 Arrays 类 ， 或 者 对 应 的 基础 类 型 包 


装 类 ， 如 /nteger。 


原生 类 型 不 能 当 作对 象 或 泛 型 的 类 型 参数 使 用 ， 这 意味 着 许多 通用 方法 都 不 能 应 用 
于 它们 。Guava 提 供 了 若干 通用 工具 ， 包 括 原 生 类 型 数组 与 集合 API 的 交互 ， 原 生 
类 型 和 字 节 数组 的 相互 转换 ， 以 及 对 某 些 原生 类 型 的 无 符号 形式 的 支持 。 


原生 类 型 ”Guava** 工 具 类 (都 在 com.google.common.primitives 包 **) 


byte Bytes , SignedBytes , UnsignedBytes 

short Shorts 

int Ints , UnsignedInteger , UnsignedInts 
long Longs , UnsignedLong , UnsignedLongs 
float Floats 

double Doubles 

char Chars 

boolean Booleans 


Bytes 工 具 类 没有 定义 任何 区 分 有 符号 和 无 符号 字 节 的 方法 ， 而 是 把 它们 都 放 到 了 
SignedBytes 和 UnsignedBytes 工 具 类 中 ， 因 为 字 节 类 型 的 符号 性 比 起 其 它 类 型 要 略 
微 含 糊 一 些 。 


int 和 long 的 无 符号 形式 方法 在 Unsignedlnts 和 UnsignedLongs 类 中 ， 但 由 于 这 两 个 
类 型 的 大 多 数 用 法 都 是 有 符号 的 ，Ints 和 Longs 类 按照 有 符号 形式 义理 方法 的 输入 参 
数 。 

此 外 ，Guava 为 int 和 long 的 无 符号 形式 提供 了 包装 类 ， 即 Unsignedlnteger 和 
UnsignedLong， 以 帮助 你 使 用 类 型 系统 ， 以 极 小 的 性 能 消耗 对 有 符号 和 无 符号 值 
进行 强制 转换 。 


在 本 章 下 面 描述 的 方法 签名 中 ， 我 们 用 Wrapper 表 示 JDK 包 装 类 ，prim 表 示 原 生 类 
型 。 (Prims 表 示 相 应 的 Guava 工 具 类 。) 


原生 类 型 数组 工具 


原生 类 型 数组 是 处 理 原生 类 型 集合 的 最 有 效 方式 (从 内 存 和 性 能 双方 面 考虑 ) o 
Guava 为 此 提供 了 许多 工具 方法 。 


方法 签名 描述 类 似 方 法 
List<Wrapper> asList(prim... ”把 数组 转 为 相应 包 


Arrays.asList 


backingArray) 装 类 的 List 
f RAH NAR 

prim{] ; oe RA 
toArray(Collection<Wrapper> = Collection.toArray() 
collection) collection.toArray() 

一 样 线程 安全 

¥ 多 个 米 型 

prim[] concat(prim[]... arrays) ad 原生 类型 lterables.concat 
boolean contains(priml] 判断 原生 类 型 数组 ' ! 
array, prim target) 是 否 包含 给 定 值 ns 

给 定 值 在 数组 中 首 
int indexOf(prim[] array, prim ”次 出 现 处 的 索引 ， ee 
target) 若 不 包含 此 值 返 List.indexOf 

回 -1 

给 定 值 在 数组 最 后 


int lastlndexOf(prim[] array, 
prim target) 


出 现 的 索引 ， 若 不 
包含 此 值 返 回 -1 


List.lastIndexOf 


prim min(prim... array) 数组 中 最 小 的 值 Collections.min 
prim max(prim... array) 数组 中 最 大 的 值 Collections.max 


String join(String separator, 把 数组 用 给 定 分 隔 imesema 


prim... array) 符 连 接 为 字符 串 
Comparator<prim[]> 按 字 典 序 比 较 原生 
p p 类 型 数组 的 Ordering.natural().lexicog 


lexicographicalComparator() Comparator 


* 符 号 无 关 方 法 存在 于 Bytes, Shorts, Ints, Longs, Floats, Doubles, Chars, 
Booleans。 而 Unsignedlnts, UnsignedLongs, SignedBytes, 或 UnsignedBytes 不 存 
在 。 


* 符 号 相关 方法 存在 于 SignedBytes, UnsignedBytes, Shorts, Ints, Longs, Floats, 
Doubles, Chars, Booleans, Unsignedlnts, UnsignedLongs。 而 Bytes 不 存在 。 


通用 工具 方法 


Guava 为 原生 类 型 提供 了 若干 JDK6 没 有 的 工具 方法 。 但 请 注意 ， 其 中 某 些 方法 已 经 
存在 于 JDK7 中 。 


方法 签名 描述 可 用 性 


1 l 传统 的 Comparator.compare 方 法 ， 但 针对 
ComparelpPnm 原生 类 型 。JDK7 的 原生 类 型 包装 类 也 提供 。 符号 相关 
pee) 这 样 的 方法 


prim 把 给 定 long 值 转 为 某 一 原生 类 型 ， 若 给 定 仅 适 用 于 
checkedCast(long 值 不 符合 该 原生 类 型 ， 则 抛 出 符号 相关 
value) lllegalArgumentException 的 整 型 * 
piim 把 给 定 long 值 转 为 某 一 原生 类 型 ， 若 给 定 。， 仅 到 用 于 
saturatedCast(lon - Se a 符号 相关 
(ong ， 和 值 不 符合 则 使 用 最 接近 的 原生 类 型 值 


* 这 里 的 整 型 包括 byte, short, int, long。 不 包括 char boolean, float, 或 double。 


** 译 者 注 : 不 符合 主要 是 指 /ong 值 超出 prim 类 型 的 范围 ， 比 如 过 大 的 /ong 超 出 int 范 
围 。 


注 : com.google.common.math.DoubleMath 提 供 了 舍 入 double 的 方法 ， 支 持 多 种 
舍 入 模式 。 相 见 第 12 章 的 " 浮 点 数 运算 ”。 


字 节 转换 方法 


Guava 提 供 了 若干 方法 ， 用 来 把 原生 类 型 按 大 字 节 序 与 字 节 数组 相互 转换 。 所 有 这 
些 方法 都 是 符号 无 关 的 ， 此 外 Booleans 没 有 提供 任何 下 面 的 方法 。 


方法 或 字段 签名 描述 


int BYTES 常量 : 表示 该 原生 类 型 需要 的 字 节 数 
prim 使 用 字 节 数组 的 前 Prims.BYTES 个 字 节 ， 按 大 字 节 序 返 


fromByteArray(byte[] ， 回 原生 类 型 值 ; 如 果 bytes.length <= Prims.BYTES, 
bytes) 抛 出 IAE 


prim fromBytes(byte ， 接受 Prims.BYTES 个 字 节 参数 ， 按 大 字 节 序 返回 原生 类 
b1, ..., byte bk) 型 什 


byte[] 
toByteArray(prim 按 大 字 节 序 返 回 value 的 字 节 数组 
value) 


无 符号 支持 


JDK 原 生 类 型 包装 类 提供 了 针对 有 符号 类 型 的 方法 ， 而 Unsignedlnts 和 
UnsignedLongs 工 具 类 提供 了 相应 的 无 符号 通用 方法 。Unsignedlnts 和 
UnsignedLongs 直 接 处 理 原生 类 型 : 使 用 时 ， 由 你 自己 保证 只 传人 了 无 符号 类 型 的 
值 。 


此 外 ， 对 int 和 long，Guava 提 供 了 无 符号 包装 类 (Unsignedlnteger 和 
UnsignedLong) ， 来 帮助 你 以 极 小 的 性 能 消耗 ， 对 有 符号 和 无 符号 类 型 进行 强制 转 
换 。 

无 符号 通用 工具 方法 

JDK 的 原生 类 型 包装 类 提供 了 有 符号 形式 的 类 似 方法 。 


方法 签名 


int UnsignedInts.parseUnsignedInt(String) long UnsignedLongs.pars 


Google Guava 中 文教 程 


int UnsignedInts.parseUnsignedInt(String string, int radix) long 


String UnsignedInts.toString(int) String UnsignedLongs.toString(l 


String UnsignedInts.toString(int value, int radix) String Unsigne 


无 符号 包装 类 包含 了 若干 方法 ， 让 使 用 和 转换 更 容易 。 
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方法 签名 


UnsignedPrim 
add(UnsignedPrim), 


subtract, multiply, divide, 


remainder 


UnsignedPrim 
valueOf(BigInteger) 


UnsignedPrim 
valueOf(long) 


UnsignedPrim 
asUnsigned(prim value) 


BigInteger 
bigIntegerValue() 


toString(), toString(int 
radix) 


说 明 


按 给 定 Biglnteger 返 回 无 符号 对 象 ， 若 Biglnteger 
为 负 或 不 匹配 ， 抛 出 IAE 


按 给 定 long 返 回 无 符号 对 象 ， 若 long 为 负 或 不 匹 
配 ， 抛 出 IAE 


把 给 定 的 值 当 作 无 符号 类 型 。 例 如 ， 
UnsignedlntegerasUnsigned(1<<31) 的 值 为 
2<sup>31</sup>, 尽 管 1<<31 当 作 int 时 是 负 的 


用 Biglnteger 返 回 该 无 符号 对 象 的 值 


返回 无 符号 值 的 字符 串 表示 


9-1/0 


原文 链接 译文 链接 译 者 : 沈 义 扬 


字 节 流 和 字符 流 


Guava 使 用 术语 ” 流 ” 来 表示 可 关闭 的 ， 并 且 在 底层 资源 中 有 位 置 状 态 的 MO 数据 流 。 
术语 " 字 节 流 " 指 的 是 InputStream 或 OutputStream，" 字 符 流 " 指 的 是 Reader 或 
Writer (虽然 他 们 的 接口 Readable 和 Appendable 被 更 多 地 用 于 方法 参数 ) 。 相 应 
的 工具 方法 分 别 在 ByteStreams 和 CharStreams 中 。 


大 多 数 Guava 流 工具 一 次 处 理 一 个 完整 的 流 ， 并 且 / 或 者 为 了 效率 自己 处 理 缓冲 。 还 
要 注意 到 ， 接 受 流 为 参数 的 Guava 方 法 不 会 关闭 这 个 流 : 关闭 流 的 职责 通常 属于 打 
流 的 代码 块 。 


其 中 的 一 些 工 具 方 法 列举 如 下 : 


ByteStreams CharStreams 

byte[] toByteArray(InputStream) String toString(Readable) 
N/A List&lt;String&gt; readLi 
long copy(InputStream, OutputStream) long copy(Readable, Appen 
void readFully(InputStream, byte[]) N/A 

void skipFully(InputStream, long) void skipFully(Reader, lo 
OutputStream nullOutputStream( ) Writer nullwriter() 


KF InputSupplier 和 OutputSupplier 要 注意 : 


在 ByteStreams、CharStreams 以 及 com.google.common.io 包 中 的 一 些 其 他 类 中 ， 

某 些 方法 仍然 在 使 用 InputSupplier 和 OutputSupplier 接 口 。 这 两 个 借口 和 相关 的 方 
法 是 不 推荐 使 用 的 : 它们 已 经 被 下 面 描述 的 source 和 sink 类 型 取代 了 ， 并 且 最 终 会 
被 移 除 。 


RS 


通常 我 们 都 会 创建 MO 工具 方法 ， 这 样 可 以 避免 在 做 基础 运算 时 总 是 直接 和 流 打 交 
道 。 例 如 ，Guava 有 Files.toByteArray(File) 和 Files.write(File, byte[])。 然 而 ， 流 工 
具 方 法 的 创建 经 常 最 终 导 致 散落 各 处 的 相似 方法 ， 每 个 方法 读 取 不 同类 型 的 源 


或 写 入 不 同类 型 的 汇 [sink]。 例 如 ，Guava 中 的 Resources.toByteArray(URL) 和 
Files.toByteArray(File) 做 了 同样 的 事情 ， 只 不 过 数据 源 一 个 是 URL， 一 个 是 文件 。 


为 了 解决 这 个 问题 ，Guava 有 一 系列 关于 源 与 汇 的 抽象 。 源 或 汇 指 某 个 你 知道 如 何 
从 中 打开 流 的 资源 ， 比 如 File 或 URL。 源 是 可 读 的 ， 汇 是 可 写 的 。 此 外 ， 源 与 汇 按 
照 字 节 和 字符 划分 类 型 。 


Fý 字符 
读 ByteSource CharSource 
5 ByteSink CharSink 


源 与 汇 API 的 好 处 是 它们 提供 了 通用 的 一 组 操作 。 上 比如 ， 一 旦 你 把 数据 源 包 装 成 了 
ByteSource， 无 论 它 原先 的 类 型 是 什么 ， 你 都 得 到 了 一 组 按 字 节 操作 的 方法 。 


创建 源 与 汇 


Guava 提 供 了 若干 源 与 汇 的 实现 : 


Pa 字符 
Files.asByteSource(File) Files.asCharSource(Fi 
Files.asByteSink(File, FileWriteMode...) Files.asCharSink(File 
Resources.asByteSource(URL) Resources.asCharSourc 
ByteSource.wrap(byte[ ] ) CharSource.wrap(CharS 
ByteSource.concat(ByteSource...) CharSource.concat(Cha 
ByteSource.slice(long, long) N/A 

N/A ByteSource.asCharSour 

N/A ByteSink.asCharSink(C 


此 外 ， 你 也 可 以 继承 这 些 类 ， 以 创建 新 的 实现 。 


注 : 把 已 经 打开 的 流 (比如 InputStream) 包装 为 源 或 汇 听 起 来 是 很 有 诱惑 力 的 ， 

但 是 应 该 避免 这 样 做 。 源 与 汇 的 实现 应 该 在 每 次 openStream() 方 法 被 调用 时 都 创建 
一 个 新 的 流 。 始 终 创 建新 的 流 可 以 让 源 或 汇 管理 流 的 整个 生命 周期 ， 并 且 让 多 次 调 
用 openStream() 返 回 的 流 都 是 可 用 的 。 此 外 ， 如 果 你 在 创建 源 或 江 之 前 创建 了 流 ， 
oe eer 己 保 证 关闭 流 ， 这 压根 就 违背 了 发 挥 源 与 汇 API 优 点 的 初 


使 用 源 与 汇 
一 旦 有 了 源 与 汇 的 实例 ， 就 可 以 进行 若干 读 写 操作 。 
通用 操作 


所 有 源 与 汇 都 有 一 些 方法 用 于 打开 新 的 流 用 于 读 或 写 。 上 默认 情况 下 ， 其 他 源 与 汇 操 
作 都 是 先 用 这 些 方法 打开 流 ， 然 后 做 一 些 读 或 写 ， 最 后 保证 流 被 正确 地 关闭 了 。 这 
些 方 法 列举 如 下 : 


e openStream() : 根据 源 与 汇 的 类 型 ， 返 回 InputStream、OutputStream、 
Reader 或 者 Writer。 

e openBufferedStream() : 根据 源 与 江 的 类 型 ， 返 回 InputStream、 
OutputStream、BufferedReader 或 者 BufferedWriter。 返 回 的 流 保 证 在 必要 情 
况 下 做 了 缓冲 。 例 如 ， 从 字 节 数组 读数 据 的 源 就 没有 必要 再 在 内 存 中 作 缓 冲 ， 
这 就 是 为 什么 该 方法 针对 字 节 源 不 返回 BufferedlnputStream。 字 符 源 属于 例外 
情况 ， 它 一 定 返回 BufferedReader， 因 为 BufferedReader 中 才 有 readLine() 方 


/Ao 


源 操作 
字 节 源 字符 源 
byte[] read() String read() 
N/A ImmutableList&lt;String&gt; 
N/A String readFirstLine() 
long copyTo(ByteSink ) long copyTo(CharSink) 
long copyTo(OutputStream) long copyTo(Appendable) 
long size() (in bytes) N/A 
boolean isEmpty() boolean isEmpty() 


boolean contentEquals(ByteSource) N/A 


HashCode hash(HashFunction) N/A 
汇 操作 
字 节 汇 字符 汇 
void write(byte[]) void write(CharSequence) 
long writeFrom( InputStream) long writeFrom( Readable) 
N/A void writeLines(Iterable&lt;? exte 
N/A void writeLines(Iterable&lt;? exte 


Eh 


//Read the lines of a UTF-8 text file 
ImmutableList<String> lines = Files.asCharSource(file, Charsets.UTI 
//Count distinct word occurrences in a file 
Multiset<String> wordOccurrences = HashMultiset.create( 
Splitter.on(CharMatcher .WHITESPACE ) 
.trimResults() 
.omitEmptyStrings() 
.Split(Files.asCharSource(file, Charsets.UTF_8).read()_ 


//SHA-1 a file 
HashCode hash = Files.asByteSource(file).hash(Hashing.sha1()); 


//Copy the data from a URL to a file 
Resources.asByteSource(url).copyTo(Files.asByteSink(file) ); 


a Ă— 


文件 操作 


除了 创建 文件 源 和 文件 的 方法 ，Files 类 还 包含 了 若干 你 可 能 感 兴趣 的 便利 方法 。 





T 


createParentDirs(File) 必要 时 为 文件 创建 父 目 录 
getFileExtension(String) 返回 给 定 路 径 所 表示 文件 的 扩展 名 


getNamewithoutExtension(String) 返回 去 除了 扩展 名 的 文件 名 


规范 文件 路 径 ， 并 不 总 是 与 文件 系 
统一 致 ， 请 仔细 测试 


fileTreeTraverser() 返回 TreeTraverser 用 于 通 历 文件 树 


simplifyPath(String) 


10- 获 列 


原文 链接 译文 链接 译 者 : 沈 义 扬 


概述 


Java 内 建 的 散 列 码 [hash code] 概 念 被 限制 为 32 位 ， 并 且 没 有 分 离散 列 算法 和 它们 所 
作用 的 数据 ， 因 此 很 难 用 各 选 算法 进行 替换 。 此 外 ， 使 用 Java 内 建 方 法 实现 的 散 列 
码 通常 是 劣质 的 ， 部 分 是 因为 它们 最 终 都 依赖 于 JDK 类 中 已 有 的 劣质 散 列 码 。 


Object.hashCode 往 往 很 快 ， 但 是 在 预防 碰撞 上 却 很 弱 ， 也 没有 对 分 散 性 的 预期 。 

这 使 得 它们 很 适合 在 散 列 表 中 运用 ， 因 为 额外 碰撞 只 会 带 来 轻微 的 性 能 损失 ， 同 时 
差劲 的 分 散 性 也 可 以 容易 地 通过 再 散 列 来 纠正 (Java 中 所 有 合理 的 散 列 表 都 用 了 再 
散 列 方法 ) 。 然 而 ， 在 简单 散 列 表 以 外 的 散 列 运用 中 ，Object.hashCode 几 乎 总 是 





达 不 到 要 求 因此 ， 有 了 com.google.common.hash 包 。 
散 列 包 的 组 成 


在 这 个 包 的 Java doc 中 ， 我 们 可 以 看 到 很 多 不 同 的 类 ， 但 是 文档 中 没有 明显 地 表明 
一 起 配合 工作 的 。 在 介绍 散 列 包 中 的 类 之 前 ， 让 我 们 先 来 看 下 面 这 段 代 
码 范 例 : 


HashFunction hf = Hashing.md5(); 
HashCode hc = hf.newHasher() 
. putLong(id) 
.putString(name, Charsets.UTF_8) 
.putObject(person, personFunnel) 
.hash(); 


HashFunction 


HashFunction 是 一 个 单纯 的 (引用 透明 的 ) 、 无 状态 的 方法 ， 它 把 任意 的 数据 块 映 
射 到 固定 数目 的 位 指 ， 并 且 保 证 相同 的 输入 一 定 产生 相同 的 输出 ， 不 同 的 输入 尽 可 
能 产生 不 同 的 输出 。 


Hasher 


HashFunction 的 实例 可 以 提供 有 状态 的 Hasher，Hasher 提 供 了 流畅 的 语法 把 数据 
添加 到 散 列 运算 ， 然 后 获取 散 列 值 。Hasher 可 以 接受 所 有 原生 类 型 、 字 节 数 组 、 字 
Me 
现 的 对 象 。 


Hasher 实 现 了 PrimitiveSink 接 口 ， 这 个 接口 为 接受 原生 类 型 流 的 对 象 定义 了 fluent 
风格 的 API 


Funnel 


Funnel 描 述 了 如 何 把 一 个 具体 的 对 象 类 型 分 解 为 原生 字段 值 ， 从 而 写 入 
PrimitiveSink。 比 如 ， We 样 一 个 类 : 


class Person { 
final int id; 
final String firstName; 
final String lastName; 
final int birthYear; 


它 对 应 的 Funnel 实 现 可 能 是 : 


Funnel<Person> personFunnel = new Funnel<Person>() { 
@Override 
public void funnel(Person person, PrimitiveSink into) { 
into 

.putInt(person.id) 
.putString(person.firstName, Charsets.UTF_8) 
.putString(person.lastName, Charsets.UTF_8) 
.putInt(birthyYear ); 


注 : putString(“abc”, Charsets. UTF_8).putString(“def’, Charsets.UTF_ 8) 完全 等 同 
FputString(“ab”, e lls _8).putString(“cdef’, Charsets.UTF 8)， 因 为 它们 
提供 了 相同 的 字 节 序列 。 能 带 来 预料 之 外 的 散 列 冲突 。 增 加 某 种 形式 的 分 隔 符 
有 助 于 消除 散 列 冲突 。 


HashCode 


一 旦 Hasher 被 赋予 了 所 有 输入 ， 就 可 以 通过 hash() 方 法 获取 HashCode 实 例 ( 多 次 
调用 hash() 方 法 的 结果 是 不 确定 的 ) 。HashCode 可 以 通过 

asint(), asLong(), asBytes() 方 法 来 做 相等 性 检测 ， 此 外 ，writeBytesTo(array, 
offset, maxLength) 把 散 列 值 的 前 maxLength 字 节 写 入 字 节 数组 。 


布 鲁 姆 过 滤器 [BloomFilter] 


布 鲁 姆 过 滤器 是 哈 希 运 算 的 一 项 优雅 运用 ， 它 可 以 简单 地 基于 Object. hashCode() 实 
mo AMEZ, ea 种 概率 数据 结构 ， 它 允许 你 检测 某 个 对 象 是 一 定 
不 在 过 滤器 中 ， 还 是 可 能 已 经 添加 到 过 滤器 了 。 布 鲁 姆 过 滤器 的 维基 页 面 对 此 作 了 


全 面 的 介绍 ， 同 时 我 们 推荐 github 中 的 一 个 教程 。 


Guava 散 列 包 有 一 个 内 建 的 布 鲁 姆 过 滤器 实现 ， 你 只 要 提供 Funnel 就 可 以 使 用 它 。 
你 可 以 使 用 create(Funnel funnel, int expectedlnsertions, double 
falsePositiveProbability) 方 法 获取 BloomFilter<T>， 缺 省 误 检 率 
[falsePositiveProbability] 为 3%。BloomFilter<T> 提 供 了 boolean mightContain(T) 和 
void put(T)， 它 们 的 含义 都 不 言 自明 了 。 


BloomFilter<Person> friends = BloomFilter.create(personFunnel, 500, 
for(Person friend : friendsList) { 

friends.put(friend); 
} 


// 很 久 以 后 
if (friends.mightContain(dude)) { 

//dude 不 是 朋友 还 运行 到 这 里 的 概率 为 1% 

// 在 这 儿 ， 我 们 可 以 在 做 进一步 精确 检查 的 同时 触发 一 些 异步 加 载 
} 


到 —_ B 





Hashing # 
Hashing 类 提供 了 若干 散 列 函数 ， 以 及 运算 HashCode 对 象 的 工具 方法 。 
已 提供 的 散 列 函数 


md5() murmur3_128() murmur3_32() sha1() 


sha256() sha512() goodFastHash(int bits) 


HashCodeiz & 


Google Guava 中 文教 程 


方法 


HashCode combineOrdered( Iterable&lt;HashCode&gt;) 


HashCode combineUnordered( Iterable&lt;HashCode&gt;) 


int consistentHash( HashCode, int buckets) 


10- 散 列 


描述 


以 有 序 方 
式 联接 散 
列 码 ， 如 
RADNE 
列 集合 用 
该 方法 联 
接 出 的 散 
列 码 相 

lal, ABA 
散 列 集合 
的 元 素 可 
能 是 顺序 
相等 的 


以 无 序 方 
式 联接 散 
列 码 ， 如 
RADNE 
列 集合 用 
该 方法 联 
接 出 的 散 
列 码 相 

fal, ABA 
散 列 集合 
的 元 素 可 
能 在 某 种 
排序 下 是 
相等 的 


为 给 定 

的 " 桶 "大 
小 返回 一 
致 性 哈 希 
值 。 

当 ” 桶 " 堆 
长 时 ， 该 
方法 保证 
最 小 程度 
的 一 致 性 
哈 希 值 变 
化 。 详 见 
一 致 性 哈 
希 。 


11- 事 件 总 线 


原文 链接 译文 连接 译 者 : 沈 义 扬 


传统 上 ，Java 的 进程 内 事件 分 发 都 是 通过 发 布 者 和 订阅 者 之 间 的 显 式 注册 实现 的 。 
设计 EventBus 就 是 为 了 取代 这 种 显示 注册 方式 ， 使 组 件 间 有 了 更 好 的 解 耦 。 
EventBus 不 是 通用 型 的 发 布 -订阅 实现 ， 不 适用 于 进程 间 通 信 。 


SBAI 


// Class is typically registered by the container. 
class EventBusChangeRecorder { 
@Subscribe public void recordCustomerChange(ChangeEvent e) { 
recordChange(e.getChange()); 


} 


// somewhere during initialization 
eventBus.register(new EventBusChangeRecorder()); 
// much later 
public void changeCustomer() { 
ChangeEvent event = getChangeEvent(); 
eventBus.post(event); 


一 分 钟 指南 
把 已 有 的 进程 内 事件 分 发 系统 迁移 到 EventBus 非 常 简单 


事件 监听 者 [Listeners] 


监听 特定 事件 (40, CustomerChangeEvent) 


o 传统 实现 : 定义 相应 的 事件 监听 者 类 ， 如 CustomerChangeEventListener ; 
e EventBus 实 现 : 以 CustomerChangeEvent 为 唯一 参数 创建 方法 ， 并 
用 Subscribe 注 解 标 记 。 


把 事件 监听 者 注册 到 事件 生产 者 : 


o 传统 实现 : 调用 事件 生产 者 的 registerCustomerChangeEventListener 方 法 ; 这 
些 方 法 很 少 定义 在 公共 接口 中 ， 因 此 开发 者 必须 知道 所 有 事件 生产 者 的 类 型 ， 
才能 正确 地 注册 监听 者 ; 

e EventBus 实 现 : 在 EventBus 实 例 上 调用 EventBus.register(Object) 方 法 ; 请 保 
证 事件 生产 者 和 监听 者 共享 相同 的 EventBus 实 例 。 


按 事件 超 类 监听 (A0, EventObjectH Æ Object) 
e 传统 实现 : 很 困难 ， 需 要 开发 者 自己 去 实现 匹配 逻辑 ; 
e EventBus 实 现 : EventBus 自 动 把 事件 分 发 给 事件 超 类 的 监听 者 ， 并 且 人 允许 监 
听 者 声明 监听 接口 类 型 和 泛 型 的 通配符 类 型 (wildcard， 如 ? super XXX) 。 
仿 测 没有 监听 者 的 事件 : 
e 传统 实现 : 在 每 个 事件 分 发 方法 中 添加 逻辑 代码 (也 可 能 适用 AOP) 


e EventBus 实 现 : 监听 DeadEvent ; EventBus 会 把 所 有 发 布 后 没有 监听 者 处 理 
的 事件 包装 为 DeadEvent (对 调试 很 便利 ) 。 


事件 生产 者 [Producers] 
管理 和 追踪 监听 者 : 


e 传统 实现 : 用 列表 管理 监听 者 ， 还 要 考虑 线程 同步 ; 或 者 使 用 工具 类 ， 如 
EventListenerList ; 
e EventBus 实 现 : EventBus 内 部 已 经 实现 了 监听 者 管理 。 


向 监听 者 分 发 事件 : 


e 传统 实现 : 开发 者 自己 写 代 码 ， 包 括 事 件 类 型 匹配 、 异 常 处 理 、 异 步 分 发 ; 
e EventBus 实 现 : 把 事件 传递 给 EventBus.post(Object) 方 法 。 异 步 分 发 可 以 直 
接 用 EventBus 的 子 类 AsyncEventBus。 


术语 表 
事件 总 线 系统 使 用 以 下 术语 描述 事件 分 发 : 


事件 ”可 以 向 事件 总 线 发 布 的 对 象 
订阅 向 事件 总 线 注册 监听 者 以 接受 事件 的 行为 


提供 一 个 处 理 方法 ， 希 望 接受 和 处理 事件 的 对 象 


处 理 监听 者 提供 的 公共 方法 ， 事 件 总 线 使 用 该 方法 向 监听 者 发 送 事 件 ; 该 
方法 方法 应 该 用 Subscribe 注 解 


发 布 通过 事件 总 线 向 所 有 匹配 的 监听 者 提供 事件 


弟 见 问题 解答 [FAQ] 


为 什么 一 定 要 创建 *EventBus** 实 例 ， 而 不 是 使 用 单 例 模 式 ? 


EventBus 不 想 给 定 开 发 者 怎么 使 用 ; 你 可 以 在 应 用 程序 中 按照 不 同 的 组 件 、 上 下 文 
或 业务 主题 分 别 使 用 不 同 的 事件 总 线 。 这 样 的 话 ， 在 测试 过 程 中 开启 和 关闭 某 个 部 
分 的 事件 总 线 ， 也 会 变 得 更 简单 ， 影 响 范 围 更 小 。 


当然 ， 如 果 你 想 在 进程 范围 内 使 用 唯一 的 事件 总 线 ， 你 也 可 以 自己 这 人 么 做 。 比 如 在 
容器 中 声明 EventBus 为 全 局 单 例 ， 或 者 用 一 个 静态 字段 存放 EventBus， 如 果 你 喜 
欢 的 话 。 


简 而 言 之 ，EventBus 不 是 单 例 模式 ， 是 因为 我 们 不 想 为 你 做 这 个 决定 。 你 喜欢 怎么 
用 就 怎么 用 吧 。 


可 以 从 事件 总 线 中 注销 监听 者 吗 ? 
当然 可 以 ， 使 用 EventBus.unregister(Object) 方 法 ， 但 我 们 发 现 这 种 需求 很 少 : 


。 大 多 数 监 听 者 都 是 在 启动 或 者 模块 懒 加 载 时 注册 的 ， 并 且 在 应 用 程序 的 整个 生 
命 周 期 都 存在 ; 

e。 可 以 使 用 特定 作用 域 的 事件 总 线 来 处 理 临 时 事件 ， 而 不 是 注册 /注销 监听 者 ; 比 
如 在 请 求 作 用 域 [request-scoped] 的 对 象 间 分 发 消息 ， 就 可 以 同样 适用 请 求 作 
用 域 的 事件 总 线 ; 

。 销毁 和 重建 事件 总 线 的 成 本 很 低 ， 有 时 候 可 以 通过 销毁 和 重建 事件 总 线 来 更 改 
分 发 规则 。 


为 什么 使 用 注解 标记 义理 方法 ， 而 不 是 要 求 监听 者 实现 接口 ? 


我 们 觉得 注解 和 实现 接口 一 样 传达 了 明确 的 语义 ， 甚 至 可 能 更 好 。 同 时 ， 使 用 注解 
也 允许 你 把 处 理 方法 放 到 任何 地 方 ， 和 使 用 业务 意图 清晰 的 方法 命名 。 


传统 的 Java 实 现 中 ， 监 听 者 使 用 方法 很 少 的 接口 一 一 通常 只 有 一 个 方法 。 这 样 做 有 


一 些 缺点 


eo 监听 者 类 对 给 定 事 件 类 型 ， 只 能 有 单一 处 理 逻 辑 ; 

监听 者 接口 方法 可 能 冲突 ; 

。 方法 命名 只 和 事件 相关 (handleChangeEvent) ， 不 能 表达 意图 
(recordChangelnJournal) ; 

而 没有 按 类 型 定义 的 公共 父 接口 (如 所 有 的 Ul 事件 接 
口 ) 。 


接口 实现 监听 者 的 方式 很 难 做 到 简洁 ， 这 甚至 引出 了 一 个 模式 ， 尤 其 是 在 Swing 应 
用 中 ， 那 就 是 用 匿名 类 实现 事件 监听 者 的 接口 。 比 较 以 下 两 种 实现 : 


class ChangeRecorder { 
void setCustomer(Customer cust) { 
cust.addChangeListener(new ChangeListener() { 
public void customerChanged(ChangeEvent e) { 
recordChange(e.getChange()); 


}; 


// 这 个 监听 者 类 通常 由 容器 注册 给 事件 总 线 
class EventBusChangeRecorder { 
@Subscribe public void recordCustomerChange(ChangeEvent e) { 
recordChange(e.getChange()); 
} 


第 二 种 实现 的 业务 意图 明显 更 加 清晰 : 没有 多 余 的 代码 ， 并 且 人 处理 方 法 的 名 字 是 清 
晰 和 有 意义 的 。 


通用 的 监听 者 接口 *Handler<T>** 怎 么 样 ? 


有 些 人 已 经 建议 过 用 泛 型 定义 一 个 通用 的 监听 者 接口 Handler<T>。 这 有 点 这 扯 到 
Java 类 型 擦 除 的 问题 ， 假 设 我 们 有 如 下 这 个 接口 : 


interface Handler<T> { 
void handleEvent(T event); 
} 


因为 类 型 擦 除 ，Java 禁 止 一 个 类 使 用 不 同 的 类 型 参数 多 次 实现 同一 个 泛 型 接口 〈 即 
不 可 能 出 现 MultiHandler implements Handler<Type1>, Handler<Type2>) 。 这 比 
起 传统 的 Java 事 件 机 制 也 是 巨大 的 退步 ， 至 少 传统 的 Java Swing 监听 者 接口 使 用 了 
不 同 的 方法 把 不 同 的 事件 区 分 开 。 


EventBus** 不 是 破坏 了 静态 类 型 ， 排 斥 了 自动 重 构 支 持 吗 ?** 


有 些 人 被 EventBus 的 register(Object) 和 post(Object) 方 法 直接 使 用 Object 做 参数 吓 
坏 了 。 


这 里 使 用 Object 参数 有 一 个 很 好 的 理由 : EventBus 对 事件 监听 者 类 型 和 事件 本 身 的 
类 型 都 不 作 任何 限制 。 


另 一 方面 ， 处 理 方法 必须 要 明确 地 声明 参数 类 型 一 一 期 望 的 事件 类 型 (或 事件 的 父 
类 型 )。 因 此 ， 搜 索 一 个 事件 的 类 型 引用 ， 可 以 马上 找到 针对 该 事件 的 处 理 方法 ， 
对 事件 类 型 的 重 命名 也 会 在 IDE 中 自动 更 新 所 有 的 处 理 方法 。 


在 EventBus 的 架构 下 ， 你 可 以 任意 重 命 名 @Subscribe 注 解 的 义理 方法 ， 并 且 这 类 
重 命名 不 会 被 传播 〈 即 不 会 引起 其 他 类 的 修改 ) ， 因 为 对 EventBus 来 说 ， 义 理 方法 
的 名 字 是 无 关 紧 要 的 。 如 果 测 试 代码 中 直接 调用 了 义理 方法 ， 那 么 当然 ， 重 命名 义 
理 方法 会 引起 测试 代码 的 变动 ， 但 使 用 EventBus 触 发 处 理 方法 的 代码 就 不 会 发 生变 
更 。 我 们 认为 这 是 EventBus 的 特性 ， 而 不 是 漏洞 : 能 够 任意 重 命 名 处 理 方法 ， 可 以 
让 你 的 处 理 方法 命名 更 清晰 。 


如 果 我 注册 了 一 个 没有 任何 处 理 方法 的 监听 者 ， 会 发 生 什 么 ? 
什么 也 不 会 发 生 。 


EventBus 旨 在 与 容器 和 模块 系统 整合 ，Guice 就 是 个 典型 的 例子 。 在 这 种 情况 下 ， 
可 以 方便 地 让 容器 /工厂 /运行 环境 传递 任意 创建 好 的 对 象 给 EventBus 的 
register(Object) 方 法 。 


这 样 ， 任 何 容 器 /工厂 /运行 环境 创建 的 对 象 都 可 以 简便 地 通过 暴露 处 理 方法 挂 载 到 
系统 的 事件 模块 。 


编译 时 能 检测 到 *EventBus* 的 哪些 问题 ? 


Java 类 型 系统 可 以 明白 地 检测 到 的 任何 问题 。 比 如， 为 一 个 不 存在 的 事件 类 型 定义 
处 理 方法 。 


运行 时 往 *EventBus* 注 册 监 听 者 ， 可 以 立即 检测 到 哪些 问题 ? 


一 旦 调用 了 register(Object) 方法 ，EventBus 就 会 检查 监听 者 中 的 处 理 方法 是 否 结 
构 正确 的 [well-formedness]。 上 有 具体 来 说 ， 就 是 每 个 用 @Subscribe 注 解 的 方法 都 只 能 
有 一 个 参数 。 


违反 这 条 规则 将 引起 lllegalArgumentException (这 条 规则 检测 也 可 以 用 APT 在 编译 
时 完成 ， 不 过 我 们 还 在 研究 中 ) 。 


哪些 问题 只 能 在 之 后 事件 传播 的 运行 时 才 会 被 检测 到 ? 


如 果 组 件 传 播 了 一 个 事件 ， 但 找 不 到 相应 的 处 理 方法 ，EventBus 可 能 会 指出 一 个 错 
误 (通常 是 指出 @Subscribe 注 解 的 缺失 ， 或 没有 加 载 监 听 者 组 件 ) 。 


请 注意 这 个 指示 并 不 一 定 表示 应 用 有 问题 。 一 个 应 用 中 可 能 有 好 多 场景 会 故意 忽略 
某 个 事件 ， 尤 其 当 事 件 来 源 于 不 可 控 代码 时 


你 可 以 注册 一 个 处 理 方法 专门 处 理 DeadEvent 类 型 的 事件 。 每 当 EventBus 收 到 没有 
对 应 处 理 方法 的 事件 ， 它 都 会 将 其 转化 为 DeadEvent， 并 且 传 递 给 你 注册 的 
DeadEventX {HE 你 可 以 选择 记录 或 修复 该 事件 。 


怎么 测试 监听 者 和 它们 的 义理 方法 ? 


为 监听 者 的 处 理 方法 都 是 普通 方法 ， 你 可 以 简便 地 在 测试 代码 中 模拟 EventBus 调 
用 这 些 方 法 。 


为 什么 我 不 能 在 *EventBus 上 使 用 < 泛 型 魔法 >?** 


EventBus 旨 在 很 好 地 你 理 一 大 类 用 例 。 我 们 更 喜欢 针对 大 多 数 用 例 直 击 要 害 ， 而 不 
是 在 所 有 用 例 上 都 保持 体面 。 

此 外 ， 泛 型 也 让 EventBus 的 可 扩展 性 让 它 有 益 、 高 效 地 扩展 ， 同 时 我 们 对 
EventBus 的 增补 不 会 和 你 们 的 扩展 相 冲 突 一 “成 为 一 个 非常 环 手 的 问题 。 


如 果 你 真 的 很 想 用 泛 型 ，EventBus 目 前 还 不 能 提供 ， 你 可 以 提交 一 个 问题 并 且 设 计 
自己 的 替代 方案 。 











12- 数 学 运算 
原文 链接 译文 链接 译 者 : 沈 义 扬 
SEI 


int logFloor = LongMath.log2(n, FLOOR); 

int mustNotOverflow = IntMath.checkedMultiply(x, y); 
long quotient = LongMath.divide(knownMultipleOfThree, 3, RoundingM 
BigInteger nearestInteger = DoubleMath.roundToBigInteger(d, Roundir 
BigInteger sideLength = BigIntegerMath.sqrt(area, CEILING); 


4 — 4 





为 什么 使 用 Guava Math 


e Guava Math 针 对 各 种 不 常见 的 浴 出 情况 都 有 充分 的 测试 ; 对 渝 出 语义 ，Guava 
文档 也 有 相应 的 说 明 ; 如 果 运 算 的 浴 出 检查 不 能 通过 ， 将 导致 快速 失败 ; 

e Guava Math 的 性 能 经 过 了 精心 的 设计 和 调 优 ; 虽然 性 能 不 可 避免 地 依据 具体 
硬件 细节 而 有 所 差异 ， 但 Guava Math 的 速度 通常 可 以 与 Apache Commons 的 
MathUtils 相 比 ， 在 某 些 场景 下 其 至 还 有 显著 提升 ; 

e Guava Math 在 设计 上 考虑 了 可 读 性 和 正确 的 编程 习惯 ; IntMath.log2(x, 
CEILING) 所 表达 的 含义 ， 即 使 在 快速 阅读 时 也 是 清晰 明确 的 。 而 32- 
Integer.numberOfLeadingZeros(x — 们 对 于 阅读 者 来 说 则 不 够 清晰 。 


注意 : Guava Math 和 GWT 格 外 不 兼容 ， 这 是 因为 Java 和 Java Scriptig Ss Nie BiB 
出 逻辑 不 一 样 。 


整数 运算 


Guava Math 主 要 处 理 三 种 整数 类 型 : int、long 和 Biglnteger。 这 三 种 类 型 的 运算 工 
具 类 分 别 叫做 IntMath、LongMath 和 BiglntegerMath。 


有 洽 出 检查 的 运算 


Guava Math 提 供 了 若干 有 浴 出 检查 的 运算 方法 : 结果 浴 出 时 ， 这 些 方 法 将 快速 失 
败 而 不 是 忽略 浴 出 


IntMath.checkedAdd LongMath. checkedAdd 


IntMath.checkedSubtract LongMath.checkedSubtract 
IntMath.checkedMultiply LongMath.checkedMultiply 
IntMath.checkedPow LongMath.checkedPow 


IntMath.checkedAdd(Integer .MAX_VALUE, Integer.MAX_VALUE); // throws 
‘| EE 


实数 运算 


IntMath、LongMath 和 BiglntegerMath 提 供 了 很 多 实数 运算 的 方法 ， 并 把 最 终 运 算 
结果 舍 人 成 整数 。 这 些 方 法 接受 一 个 java.math.RoundingMode 枚 举 值 作为 舍 人 的 模 


式 : 








DOWN :AISAMBA (KBR) 

UP: 远离 需 方 向 舍 入 

FLOOR : 向 负 无 限 大 方向 舍 入 

CEILING : 向 正 无 限 大 方向 舍 入 

UNNECESSARY : 不 需要 舍 入 ， 如 果 用 此 模式 进行 舍 入 ， 应 直接 抛 出 
ArithmeticException 

HALF_UP : 向 最 近 的 整数 舍 入 ， 其 中 x.5 远 离 需 方向 舍 入 
HALF_DOWN : 向 最 近 的 整数 舍 入 ， 其 中 x.5 向 需 方 向 舍 入 
HALF_EVEN : 向 最 近 的 整数 舍 入 ， 其 中 x.5 向 相 邻 的 偶数 舍 入 


这 些 方法 旨 在 提高 代码 的 可 读 性 ， 例 如 ，divide(x, 3, CEILING) 即使 在 快速 阅读 时 
也 是 清晰 。 此 外 ， 这 些 方法 内 部 采用 构建 整数 近似 值 再 计算 的 实现 ， 除 了 在 构建 
sqrt GEAR) 运算 的 初始 近似 值 时 有 浮 点 运算 ， 其 他 方法 的 运算 全 过 程 都 是 整数 
或 位 运算 ， 因 此 性 能 上 更 好 。 


IntMath LongMath 


Mt a 


divide(int, int, RoundingMode) divide(long, long, Roundin 


Zio N 


log2(int, RoundingMode) log2(long, RoundingMode ) 


log10(int, RoundingMode) log10(long, RoundingMode) 


方 sqrt(int, RoundingMode) sqrt(long, RoundingMode) 


// returns 31622776601683793319988935444327185337195551393252 
BigIntegerMath.sqrt(BigInteger.TEN.pow(99), RoundingMode.HALF_EVEN | 


eS) 


附加 功能 
Guava 还 另外 提供 了 一 些 有 用 的 运算 函数 





IntMath LongMath BiglntegerMath* 


SOF (5 


Ged MERINE) gcd(long, long) BigInteger .gcd(E 


SEE bt A 


mod(int, int) mod(long, long) BigInteger .mod(E 


Hi Sa 


pow(int, int) pow(long, int) BigInteger .pow(i 


isPowerOfTwo(int ) isPowerOfTwo(long) isPowerOfTwo(Bic 


WAN TAA Wa 


factorial(int) factorial(int) factorial(int) 


* Fall 


binomial(int, int) binomial(int, int) binomial(int, ir 


* eS ES | I 


*Biglnteger 的 最 大 公约 数 和 取 模 运算 由 JDK 提 供 
* 阶 乘 和 二 项 式 系 数 的 运算 结果 如 果 浴 出 ， 则 返回 MAX_VALUE 
浮 点 数 运算 


JDK 比 较 彻 底 地 洒 盖 了 浮 点 数 运算 ， 但 Guava 在 DoubleMath 类 中 也 提供 了 一 些 有 用 
的 方法 。 


Google Guava 中 文教 程 


IsMathematicalInteger(double) 
roundToInt(double, RoundingMode) 
roundToLong(double, RoundingMode) 


roundToBigInteger (double, RoundingMode ) 


log2(double, RoundingMode) 


Y 


12- 数 学 运算 


判断 该 浮 点 数 是 不 是 一 个 
整数 

SA Aint; 对 无 限 小 数 、 
浴 出 抛 出 异常 

SA Along ; 对 无 限 小 
数 、 洽 出 抛 出 异常 

舍 人 为 Biglnteger ; 对 无 
限 小 数 抛 出 异常 


2 的 浮 点 对 数 ， 并 且 舍 入 
为 int， 比 JDK 的 
Math.log(double) 更 快 
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13- 反 射 


译 者 : DRAH) 


由 于 类 型 擦 除 ， 你 不 能 够 在 运行 时 传递 泛 型 类 对 象 
假装 这 些 对 象 是 有 泛 型 的 ， 但 实际 上 它们 没有 。 


举 个 例子 : 





你 可 能 想 强制 转换 它们 ， 并 


ArrayList<String> stringList = Lists.newArrayList(); 
ArrayList<Integer> intList = Lists.newArrayList(); 
System.out.println(stringList.getClass().isAssignableFrom(intList .<¢ 
returns true, even though ArrayList<String> is not assignable from 


Ki — 


Guava 提 供 了 TypeToken, 它 使 用 了 基于 反射 的 技巧 甚至 让 你 在 运行 时 都 能 够 巧妙 的 
操作 和 查询 泛 型 类 型 。 想 象 一 下 TypeToken 是 创建 ， 操 作 ， 查 询 泛 型 类 型 (以 及 ， 
隐 合 的 类 ) 对 象 的 方法 。 


Guice 用 户 特别 注意 : TypeToken 与 类 Guice 的 TypeLiteral 很 相似 ， 但 是 有 一 个 点 特 
别 不 同 : 它 能 够 支持 非 具 体 化 的 类 型 ， 例 如 T，List<T>， 甚 至 是 List<? extends 
Number> ; TypeLiteral 则 不 能 支持 。TypeToken 也 能 支持 序列 化 并 且 提供 了 很 多 领 
外 的 工具 方法 。 


背景 : 类 型 探 除 与 反射 


Java 不 能 在 运行 时 保留 对 象 的 泛 型 类 型 信息 。 如 果 你 在 运行 时 有 一 个 
ArrayList<String> 对 象 ， 你 不 能 够 判定 这 个 对 象 是 有 泛 型 类 型 ArrayList<String> 的 
一 一 并 且 通 过 不 安全 的 原始 类 型 ， 你 可 以 将 这 个 对 象 强 制 转 换 成 
ArrayList<Object>。 


但 是 ， 反 射 允许 你 去 检测 方法 和 类 的 泛 型 类 型 。 如 果 你 实现 了 一 个 返回 List 的 方 
法 ， 并 且 你 用 反射 获得 了 这 个 方法 的 返回 类 型 ， 你 会 获得 代表 List<String> 的 
ParameterizedType。 


TypeToken 类 使 用 这 种 变通 的 方法 以 最 小 的 语法 开销 去 支持 泛 型 类 型 的 操作 。 





介绍 
获取 一 个 基本 的 、 原 始 类 的 TypeToken 非 常 简单 : 


TypeToken<String> stringTok = TypeToken.of(String.class); 
TypeToken<Integer> intTok = TypeToken.of(Integer.class); 


为 获得 一 个 含有 泛 型 的 类 型 的 TypeToken 一 一 当 你 知道 在 编译 时 的 泛 型 参数 类 型 
你 使 用 一 个 空 的 匿名 内 部 类 : 





TypeToken<List<String>> stringListTok = new TypeToken<List<String>: 
‘| _ I $] 
或 者 你 想 故意 指向 一 个 通配符 类 型 : 








TypeToken<Map<?, ?>> wildMapTok = new TypeToken<Map<?, ?>>() {}; 


TypeToken 提 供 了 一 种 方法 来 动态 的 解决 泛 型 类 型 参数 ， 如 下 所 示 : 


static <K, V> TypeToken<Map<K，V>> mapToken(TypeToken<K> keyToken, 
return new TypeToken<Map<K, V>>() {} 
.where(new TypeParameter<K>() {}, keyToken) 
.where(new TypeParameter<V>() {}, valueToken); 


} 


TypeToken<Map<String, BigInteger>> mapToken = mapToken( 
TypeToken.of(String.class), 
TypeToken.of(BigInteger.class) 

); 

TypeToken<Map<Integer, Queue<String>>> complexToken = mapToken( 
TypeToken.of(Integer.class), 
new TypeToken<Queue<String>>() {} 





注意 如 果 mapToken 只 是 返回 了 new TypeToken>()， 它 实际 上 不 能 把 具体 化 的 类 型 
分 配 到 K 和 V 上面， 举 个 例子 


class Util { 
static <K, V> TypeToken<Map<kK, V>> incorrectMapToken() { 
return new TypeToken<Map<K, V>>() {}; 
} 


} 
System.out.println(Util.<String, BigInteger>incorrectMapToken()); 
// just prints out "java.util.Map<K, V>" 


SS | 


或 者 ， 你 可 以 通过 一 个 子 类 (通常 是 匿名 ) 来 捕获 一 个 泛 型 类 型 并 且 这 个 子 类 也 可 
以 用 来 替换 知道 参数 类 型 的 上 下 文 类 。 


abstract class IKnowMyType<T> { 
TypeToken<T> type = new TypeToken<T>(getClass()) {}; 


new IKnowMyType<String>() {}.type; // returns a correct TypeToken<; 
mi — 
使 用 这 种 技术 ， 你 可 以 ， 例 如 ， 获 得 知道 他 们 的 元 素 类 型 的 类 。 








查询 


TypeToken 支 持 很 多 种 类 能 支持 的 查询 ， 但 是 也 会 把 通用 的 查询 约束 考虑 在 内 。 
支持 的 查询 操作 包括 : 


方法 描述 
getType() 获得 包装 的 java.lang.reflect.Type. 
getRawType() 返回 大 家 熟知 的 运行 时 类 


返回 那些 有 特定 原始 类 的 子 类 型 。 举 个 例子 ， 如 果 
getSubtype(Class<?>) ”这 有 一 个 lterable 并 且 参 数 是 List.class， 那 么 返回 将 

是 List。 

2 ”产生 这 个 类 型 的 超 关 ， 这 个 超 类 是 指定 的 原始 类 

geiSupertype(Class<? 型 。 闪 个 例子 ， 如 果 这 是 一 个 Set 并 且 参 数 是 

lterable.class， 结 果 将 会 是 lterable。 

如 果 这 个 类 型 是 assignable from 指定 的 类 型 ， 并 且 
isAssignableFrom(type) ”考虑 泛 型 参数 ， 返 回 true。List<? extends Number> 

是 assignable from List， 但 List 没 有 . 

返回 一 个 Set， 包 含 了 这 个 所 有 接口 ， 子 类 和 类 是 这 
getTypes() 个 类 型 的 类 。 返 回 的 Set 同 样 提供 了 classes() 和 
interfaces() 方 法 允许 你 只 浏览 超 类 和 接口 类 。 
检查 某 个 类 型 是 不 是 数组 ， 其 至 是 <? extends 
A>. 


getComponentType() 返回 组 件 类 型 数组 。 


isArray() 


resolveType 


resolveType 是 一 个 可 以 用 来 “替代 ”context token ( 译 者 : 不 知道 怎么 翻译 ， 只 好 去 
stackoverflow 去 问 了 ) 中 的 类 型 参数 的 一 个 强大 而 复杂 的 查询 操作 。 例 如 ， 


TypeToken<Function<Integer, String>> funToken = new TypeToken<Funct 


TypeToken<?> funResultToken = funToken.resolveType(Function.class.<¢ 
// returns a TypeToken<String> 


‘ 一 








TypeToken 将 Java 提 供 的 TypeVariables 和 context token 中 的 类 型 变量 统一 起 来 。 这 
可 以 被 用 来 一 般 性 地 推断 出 在 一 个 类 型 相关 方法 的 返回 类 型 : 


TypeToken<Map<String, Integer>> mapToken = new TypeToken<Map<Strin¢ 
TypeToken<?> entrySetToken = mapToken.resolveType(Map.class.getMetl 
// returns a TypeToken<Set<Map.Entry<String, Integer>>> 


图 IE 





Invokable 


Guava 的 Invokable 是 对 java.lang.reflect.Method 和 java.lang.reflect.Constructor 的 流 
式 包 装 。 它 简化 了 常见 的 反射 代码 的 使 用 。 一 些 使 用 例子 : 


方法 是 否 是 public 的 ? 
JDK: 


Modifier .isPublic(method.getModifiers() ) 


Invokable: 


invokable.isPublic( ) 


方法 是 否 是 package private? 


JDK: 


!(Modifier.isPrivate(method.getModifiers()) || Modifier.isPublic(me 


a] 加 天 ae 





Invokable: 


invokable.isPackagePrivate( ) 


!(Modifier.isFinal(method.getModifiers()) 

|| Modifiers.isPrivate(method.getModifiers()) 

|| Modifiers.isStatic(method.getModifiers() ) 

|| Modifiers.isFinal(method.getDeclaringClass().getModifiers())) 


Invokable: 


invokable.isOverridable( ) 


方法 的 第 一 个 参数 是 否 被 定义 了 注解 @Nullable ? 
JDK: 


for (Annotation annotation : method.getParameterAnnotations[0]) { 
if (annotation instanceof Nullable) { 
return true; 
} 


return false; 
SD] 


Invokable: 


invokable.getParameters().get(0).isAnnotationPresent(Nullable.clas: 
BESE) 
构造 玉 数 和 工厂 方法 如 何 共享 同 祥 的 代码 ? 


你 是 否 很 想 重复 自己 ， 因 为 你 的 反射 代码 需要 以 相同 的 方式 工作 在 构造 画 数 和 工厂 
方法 中 ? 


Invokable 提 供 了 一 个 抽象 的 概念 。 下 面 的 代码 适合 任何 一 种 方法 或 构造 豆 数 : 





invokable.isPublic(); 
invokable.getParameters(); 
invokable.invoke(object, args); 


List 的 List.get(int) 返 回 类 型 是 什么 ? Invokable 提 供 了 与 众 不 同 的 类 型 解决 方案 : 


Invokable<List<String>, ?> invokable = new TypeToken<List<String>>| 
invokable.getReturnType(); // String.class 


4 — 








Dynamic Proxies 


newProxy() 


实用 方法 Reflection.newProxy(Class, InvocationHandler) 是 一 种 更 安全 ， 更 方便 的 
APIl， 它 只 有 一 个 单一 的 接口 类 型 需要 被 代理 来 创建 Java 动 态 代理 时 


JDK: 
Foo foo = (Foo) Proxy.newProxyInstance( 
Foo.class.getClassLoader(), 


new Class<?>[] {Foo.class}, 
invocationHandler ); 


Guava: 


Foo foo = Reflection.newProxy(Foo.class, invocationHandler); 


AbstractInvocationHandler 
有 时 候 你 可 能 想 动 态 代理 能 够 更 直观 的 支持 equals()，hashCode() 和 toString()， 那 
就 是 : 


1. 一 个 代理 实例 equal 另 外 一 个 代理 实例 ， 只 要 他 们 有 同样 的 接口 类 型 和 equal 的 
invocation handlers。 

2. 一 个 代理 实例 的 toString() 会 被 代理 到 invocation handler 的 toString()， 这 样 更 容 
易 自 定义 。 


AbstractiInvocationHandler 实 现 了 以 上 逻辑 。 


除 此 之 外 ，AbstractlnvocationHandler 确 保 传递 给 handlelnvocation(Object， 
Method, Object 由 ) 的 参数 数组 永远 不 会 空 ， 从 而 减少 了 空 指针 异常 的 机 会 。 


ClassPath 


严格 来 讲 ，Java 没 有 平台 无 关 的 方式 来 浏览 类 和 类 资源 。 不 过 一 定 的 包 或 者 工程 
下 ， 还 是 能 够 实现 的 ， 上 比方 说 ， 去 检查 某 个 特定 的 工程 的 惯例 或 者 某 种 一 直 遵 从 的 
约束 。 


ClassPath 是 一 种 实用 工具 ， 它 提供 尽 最 大 努力 的 类 路 径 扫 描 。 用 法 很 简单 : 


ClassPath classpath = ClassPath.from(classloader); // scans the cl 
for (ClassPath.ClassInfo classInfo : classpath.getTopLevelClasses(' 


= 
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在 上 面 的 例子 中 ，Classlnfo 是 被 加 载 类 的 句柄 。 它 允许 程序 员 去 检查 类 的 名 字 和 包 
的 名 字 ， 让 类 直到 需要 的 时 候 才 被 加 载 。 


值得 注意 的 是 ，ClassPath 是 一 个 尽力 而 为 的 工具 。 它 只 扫描 jar 文 件 中 或 者 某 个 文 
件 目 录 下 的 class 文 件 。 也 不 能 扫描 非 URLClassLoader 的 自 定 义 class loader 管 理 的 
class， 所 以 不 要 将 它 用 于 关键 任务 生产 任务 。 


Class Loading 


工具 方法 Reflection.initialize(Class...) 能 够 确保 特定 的 类 被 初始 化 一 一 执行 任何 静 
态 初 始 化 。 

使 用 这 种 方法 的 是 一 个 代码 异味 ， 因 为 静态 伤害 系统 的 可 维护 性 和 可 测试 性 。 在 有 
些 情况 下 ， 你 别 无 选择 ， 而 与 传统 的 框架 ， 操 作 间 ， 这 一 方法 有 助 于 保持 代码 不 那 
AH. 


